@awebai/oats 0.42.0 → 0.42.1

package/bin/oats.mjs

@@ -53,7 +53,7 @@ import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_
 
 import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
 import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
-import { formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
+import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
 const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
 import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
 import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
@@ -2498,7 +2498,7 @@ function retireCmd() {
   const planRev = flag("plan-revision"), idemKey = flag("idempotency-key");
   if (planRev === true || idemKey === true) die("--plan-revision and --idempotency-key need values");
   if ((planRev !== undefined) !== (idemKey !== undefined)) die("--plan-revision and --idempotency-key go together");
-  let replayPath = null, childrenStopped = null;
+  let replayPath = null, childrenStopped = null, plannedExtraWorktrees;
   if (planRev !== undefined) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
     // Replay first: after a successful retire the home is gone, so the receipt
@@ -2508,6 +2508,9 @@ function retireCmd() {
     let fresh;
     try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
     replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
+    // The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
+    // move or remove one that no longer reads that way when it gets to them.
+    plannedExtraWorktrees = fresh.facts.extraWorktrees;
     if (fresh.planRevision !== planRev) return args.includes("--json") ? jsonFail("E_PLAN_STALE", `the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`, { plan: fresh }) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
     // The plan promised: recorded children are STOPPED first (bounded, never
     // escalated) and retained. A child still running after the grace refuses
@@ -2521,7 +2524,7 @@ function retireCmd() {
     if (running.length) return args.includes("--json") ? jsonFail("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`, { childrenStopped, plan: fresh }) : die(`children still running: ${running.map((k) => k.instance).join(", ")}; nothing retired`);
   }
   let r;
-  try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force") }); }
+  try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}) }); }
   catch (e) { if (!e?.code) throw e; return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message); }
   if (childrenStopped) r.childrenStopped = childrenStopped;
   if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
@@ -2563,6 +2566,7 @@ function retireCmd() {
   // Preserving work and not saying so leaves the operator believing it is gone,
   // which is most of the harm of deleting it. Name the classes and the path.
   for (const line of workRecoveryLines(r)) console.log(line);
+  for (const line of extraWorktreeLines(r)) console.log(line);
   for (const w of r.warnings || []) console.log(`  WARNING: ${w}`);
   if (isSelf) console.log("This window dies in ~8s — say any goodbyes now.");
 }
@@ -3714,6 +3718,7 @@ async function serverRouteCmd() {
     }
     console.log(`Retired ${r.retired} on ${id}${r.deferred ? " (deferred completion scheduled there)" : ""}${r.rollbackIncomplete ? " — cleanup INCOMPLETE on the server, home retained there" : ""}`);
     for (const line of workRecoveryLines(r, { host: target.sshHost })) console.log(line);
+    for (const line of extraWorktreeLines(r, { host: target.sshHost })) console.log(line);
     if (r.rollbackIncomplete) {
       for (const f of r.rollbackIncomplete) console.error(`  ${f}`);
       const branch = failedSpawnBranchLine(r, r.rollbackIncomplete, { host: target.sshHost });

package/docs/desktop-cli-api.md

@@ -1923,7 +1923,11 @@ route target:
                "running":true,"identity":{"alias":"dev-a","address":"acme/dev-a"},"identityAddress":"acme/dev-a",
                "teams":[{"label":"default","team":"acme:team"}],"startedAt":"2026-09-29T10:00:00.000Z","createdAt":"2026-09-29T09:58:12.004Z",
                "model":"opus","runtimeState":null,"parentInstance":"lead","siblingInstance":null,"relation":"child","relativeTo":"lead",
-               "spawnOrigin":"instance","retirePending":false,"rollbackIncomplete":false,
+               "spawnOrigin":"instance","work":"worktree","repo":"/srv/team/ws","branch":"agents/dev-a","modelFrom":"soul",
+               "soul":{"repoKey":"github.com/acme/team","commit":"66566512…","current":"9c1e04ab…","status":"moved"},
+               "modules":[{"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
+                           "commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
+               "retirePending":false,"rollbackIncomplete":false,
                "savedRoute":false,"addressable":true,"missingRemotely":false}],
  "retireFailures":[]}
 ```
@@ -1940,9 +1944,16 @@ route target:
 - **Instance rows** relay the host's own `status --json` row: `identity`,
   `identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
   `runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
-  `relativeTo` and `spawnOrigin` are always present, `null` when the host
-  does not supply them (a host before 0.31, a fact it never recorded, or a
-  saved route the host no longer lists). Nothing is derived on this side.
+  `relativeTo` and `spawnOrigin`, and (relayed from 0.42.1) `work`, `repo`,
+  `branch`, `modelFrom`, `soul` and `modules`, are always present, `null`
+  when the host does not supply them (an older host, a fact it never
+  recorded, or a saved route the host no longer lists). Each is the
+  [local row's](#the-roster-oats-status---json) fact of the same name,
+  relayed as the host answered it. Nothing is derived on this side: `repo`
+  is a path on the host, never read here, and `soul` and `modules` are the
+  host's own drift observation (against its own members and lock), not
+  recomputed: `modules` is the drift rows, or the recorded map when the host
+  could not read its workspace, as on a local row.
 - **`waitingOnYou`** (0.40.2, [Waiting on you](#waiting-on-you)) is on a row
   only when the host's kernel reports it: a row from a host before 0.40.0,
   and a saved route the host did not list, have no such key. Absent means
@@ -2219,6 +2230,15 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
   `--delete-branch` (since 0.41.0: `this self-retire was requested with
   --delete-branch by an older OATS; retirement no longer deletes branches, so
   the branch and the worktree were left`).
+- `worktree-retained` (`data: {movedTo, branch, recordedBranch}`) and
+  `worktree-removed` (`data: {branch}`) are written to the workspace log only,
+  by the retire's worktree step. Since 0.42.1 the retire also writes one per
+  extra tree it handled
+  ([extra trees at retire](souls-and-instances.md#extra-trees-at-retire)),
+  with `extra: true` and the tree's absolute `path` added:
+  `worktree-retained` `{movedTo, branch, recordedBranch: null, extra: true,
+  path}` and `worktree-removed` `{branch, extra: true, path}`. A row without
+  `extra` is about `work/`.
 - **Incarnation.** Each row carries the writing home's `createdAt` (or
   `null` for old rows); the top-level `incarnation` is the current home's (or
   `null`). Earlier incarnations are returned as this address's history.
@@ -2438,7 +2458,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
                   "upstream":{"ref":null,"ahead":null,"behind":null},"base":{"ref":null,"ahead":null,"behind":null},"remote":null},
           "workMode":"worktree","repo":"/w/one","recordedBranch":"agents/dev-1",
           "children":[{"instance":"dev-1-child","agent":"dev","home":"/w/agents/dev/instances/dev-1-child","session":{"state":"shell","present":true,"backend":"tmux","established":true}}],
-          "ambiguous":[],"pullRequest":"unknown"},
+          "ambiguous":[],"pullRequest":"unknown",
+          "extraWorktrees":[{"path":"/w/agents/dev/instances/dev-1/.work-docs","repo":"/w/docs","branch":"agents/dev-1-docs","detachedAt":null,
+                             "disposition":"retain","movedTo":"/w/.agents/worktrees/docs/agents-dev-1-docs","reason":"…"}]},
  "defaults":{"retainWorktree":true,"deleteBranch":false,"stopChildren":true,"retainChildren":true},
  "planRevision":"4e5f6a7b8c9d0e1f2a3b4c5d","notes":["the worktree is on feat/x, not the recorded agents/dev-1; …"]}
 ```
@@ -2476,10 +2498,35 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
   there when it is not empty` in directory mode, and absent in checkout,
   attached and workspace modes. They are strings in `notes`: no other key
   changes, and `planRevision` is unaffected.
+- `facts.extraWorktrees` (0.42.1) lists the instance's
+  [extra trees](souls-and-instances.md#extra-trees-at-retire): linked
+  worktrees at `<home>/.work-*` that Git confirms. It is an array, empty when
+  there are none, in every work mode. Each row is `{path, repo, branch,
+  detachedAt, disposition, movedTo, reason}`:
+  - `path`: the tree's absolute path in the home.
+  - `repo`: its repository, the first entry of that repository's `git
+    worktree list` (the main worktree, or the bare repository).
+  - `branch`: the branch its HEAD is on, or `null`. `detachedAt`: the commit
+    when HEAD is detached, else `null`.
+  - `disposition`: `"remove"` (the tree is clean: it would be removed, its
+    branch kept), `"retain"` (it would be moved to `movedTo`, as `work/` is
+    retained) or `"refuse"` (the retire would refuse with
+    `E_WORK_PRESERVATION_FAILED` and keep the home).
+  - `movedTo`: the target for `"retain"`, else `null`.
+  - `reason`: `null` for `"remove"`, why the tree is not clean for
+    `"retain"`, why it is refused for `"refuse"`.
+
+  `notes` also carries one string per tree that says the same. The trees are
+  part of `planRevision`: a tree created, removed, dirtied or cleaned between
+  the plan and the apply, or a change of its disposition or target (another
+  directory taking the `<leaf>-N` it would move to, for example), refuses a
+  guarded apply with `E_PLAN_STALE` before anything runs. A reader that does
+  not know the key can ignore it; the `notes` strings say the same.
 
 Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
 (`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
-`-2` suffix if taken; `detached-<oid12>` when detached), state intact.
+`-2` suffix if taken; `detached-<oid12>` when detached), state intact. An
+extra tree that is not clean is moved the same way; a clean one is removed.
 
 ```text
 oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree] [--home <abs>] --json
@@ -2535,6 +2582,21 @@ A first retire prints the **raw receipt**, not an envelope:
   retire (hooks run, a recovery copied), and neither says that one happened:
   an error here is not proof that nothing happened, nor that a recovery
   exists.
+- `extraWorktrees` (0.42.1): the extra trees the retire handled, present only
+  when it handled at least one. Each row is the plan's row (`{path, repo,
+  branch, detachedAt, disposition, movedTo, reason}`) plus `outcome`:
+  `"removed"` or `"retained"`, with `movedTo` where a retained tree went. The
+  step runs only when the home is removed (not with `--keep-dir`, not when the
+  home is kept for a retry), after the hooks and before the worktree step of
+  `work/`. `--discard-worktree` does not apply to it. A locked tree
+  (`"refuse"` in the plan) stops the retire with `E_WORK_PRESERVATION_FAILED`
+  naming the tree before anything runs (no session stop, no retire hook);
+  a lock that appears during the hooks, or a move or removal Git refuses,
+  stops it at the step, after the hooks. `--force` does not bypass either;
+  the home and `work/` are kept, and trees already handled stay handled. A tree
+  that no longer matches what the applied plan said refuses with
+  `E_PLAN_STALE`, the home kept, rather than be moved or removed unplanned.
+  The key is additive.
 - `workRecovery`: `{path, classes, bytes, home, outputs?, repoCopy?,
   notCopied?, afterHooks?}`, present when a recovery was written. One retire
   writes at most one recovery directory, and `path` is that directory.
@@ -2560,10 +2622,12 @@ A first retire prints the **raw receipt**, not an envelope:
     names: a prefix that matches several entries lists each one, and a
     declared entry that does not exist is not listed. `owner` is the
     declaring capability; when two declare the same entry it is the first in
-    capability-name order. Each entry has exactly these three keys: names and
-    owners only, no sizes, hashes, modes or contents of what was left out.
-    `scope` is always `"home"` in this release. Present only when there is
-    at least one.
+    capability-name order. Since 0.42.1 the list also holds each verified
+    extra tree (`.work-<purpose>`), with `owner: "kernel:extra-worktree"`: the
+    retire handles it at its own step, never in the copy. Each entry has
+    exactly these three keys: names and owners only, no sizes, hashes, modes
+    or contents of what was left out. `scope` is always `"home"` in this
+    release. Present only when there is at least one.
   - `afterHooks`: `{home: boolean, work: boolean}`, saying which parts were
     copied again under `after-hooks/`: `after-hooks/home/` when a retire hook
     changed the home (its bytes and permission bits, the kernel's own
@@ -2615,8 +2679,9 @@ A first retire prints the **raw receipt**, not an envelope:
   `idempotencyKey` and `replayed: false`.
 
 Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
-`E_WORK_PRESERVATION_FAILED` (the home is kept; retry or
-`--discard-worktree`), `E_WORK_INSPECTION_FAILED` (the home is kept; the
+`E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
+`--discard-worktree` when it is `work/` that could not be re-homed: it does
+not apply to an extra tree), `E_WORK_INSPECTION_FAILED` (the home is kept; the
 message names the entry or the state that could not be read),
 `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
 `E_NO_ROOT`, `E_LIFECYCLE_FAILED`. A recovery whose Git status disagrees with

package/docs/desktop.md

@@ -249,14 +249,18 @@ for a password or key, and never runs anything over ssh itself.
 
 Every instance a registered server reports shows in its workspace's roster, whoever spawned it. You
 can open its terminal, start, restart, stop and remove it, and read its readiness, activity, Git
-and diffs, as for a local one. Only its pull request is not read here, since the forge reads this
+and diffs, as for a local one. The context panel's Soul tab and its Messaging & Teams list read
+through the server too (`oats inspect --server <id> --home <path>`), and its Work card, "model
+from" line and "older build" chip show the facts the server relays. Only its pull request is not read here, since the forge reads this
 computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
 <path>`), never by a bare name. Stop and Remove show the plan the server makes, and confirm
 against it.
 
 A read waits for the server: the view says "Reading from <server>…", and gives up after about
 45 seconds with "Couldn't reach <server>." When the server refuses, you see its code and message;
-nothing is read from this computer in its place. A row that can't be opened says why on the row:
+nothing is read from this computer in its place. When the server's OATS, or this computer's, lacks
+what a part of the panel needs, that part names the server and says which OATS to update, rather
+than showing nothing. A row that can't be opened says why on the row:
 Herdr no longer supported, gone from <server>, not reachable on <server>, or <server> not reached.
 For an instance a server no longer lists, the reason names the command that removes it from this
 computer (`oats server forget <server> --instance <name>`).

package/docs/release-notes/v0.42.1.md

@@ -0,0 +1,110 @@
+# OATS 0.42.1
+
+## Changed
+
+- **Remote roster rows carry the local row's work, repository, branch,
+  model-from, soul and module drift facts**
+  ([#675](https://github.com/awebai/oats/issues/675)). A remote instance
+  row (`oats server roster --json`, and the Desktop's remote roster) now
+  relays `work`, `repo`, `branch`, `modelFrom`, `soul` and `modules` from
+  the host's own `oats status --json` row, with the same names and meaning
+  as on a local row. `soul` and `modules` are the host's own drift
+  observation, relayed as it answered; nothing is recomputed on this side,
+  and `repo` is the host's path. Each is always present, `null` from a host
+  that doesn't report it (an older host, a fact it never recorded, or a saved
+  route the host no longer lists). See
+  [the remote roster](../desktop-cli-api.md#the-remote-roster-oats-server-roster---json).
+
+- **The `worktree` and `checkout` briefings allow extra trees, and give the
+  command** ([#674](https://github.com/awebai/oats/issues/674)). Both
+  briefings forbade extra Git worktrees: `worktree` said "Don't create extra
+  worktrees; `work/` is your one tree", and `checkout` said to ask for a
+  worktree-mode instance for work that needs its own branch. That
+  contradicted the shipped `oats.engineering` package, whose developer
+  briefing and `/worktrees` skill say "your work-mode briefing has the
+  command", with `.work-<purpose>` in the home as the default place. No
+  briefing gave that command. The case that needs it is a developer whose
+  one task touches several repositories of the deployment.
+
+  Both briefings now carry the same short paragraph. An extra tree is created
+  in the home, from any clone of the deployment (`oats-local.yaml` `clones:`,
+  or `<deployment>/<repo>`), from the remote's current state:
+
+  ```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 fetch runs inside the new tree, which has its own `FETCH_HEAD`, so
+  creating it moves none of the clone's refs. The paragraph also covers
+  branch names (the repository's rules, else `agents/<instance>-<purpose>`;
+  never `-C` or `-B`), pushing a tree without an upstream
+  (`git push origin HEAD:<remote-branch>`), and closing: merge each tree into
+  the PR branch or push it and name it in the hand-back, then
+  `git -C <clone> worktree remove`. `git switch` needs Git 2.23 or later.
+
+  `worktree` mode now says never to work in a shared checkout (the main
+  checkout, or any clone others use), and that changes happen in `work/` or
+  in the extra trees. It drops "Parallel work means your human spawns
+  another instance". `checkout` mode now says that work needing its own
+  branch goes in an extra tree, not in `work/`. The `workspace`, `directory`
+  and `attached` briefings do not change, and there is no new `oats`
+  command. The instance-boundary block every instance receives said repository
+  work happens in `work/` "and only there"; it now says "there, or in the
+  extra trees your mode block grants, and nowhere else", so the two blocks
+  no longer disagree. Instances spawned before the upgrade keep the briefing
+  they were spawned with. See
+  [souls and instances](../souls-and-instances.md#extra-trees).
+
+- **Retire protects extra trees in the home**
+  ([#674](https://github.com/awebai/oats/issues/674)). An extra tree is a
+  top-level `.work-*` entry of the home that Git confirms is a linked
+  worktree of some repository. Before, retire treated it as home bytes: it
+  copied it to recovery and removed it with the home, leaving the
+  repository's admin entry behind. Now, in every work mode:
+
+  - A verified extra tree is not copied to recovery. `workRecovery.notCopied`
+    lists it with `owner: "kernel:extra-worktree"`. A `.work-*` entry that
+    does not verify (a plain directory, a symbolic link, a full clone), or
+    that belongs to a repository inside the home, is copied as before.
+  - When the home is removed, the retire handles each tree after its hooks
+    and before the `work/` worktree step. A clean tree (empty status,
+    ignored and untracked files included; no operation in progress; HEAD
+    reached by a ref of its repository, not only by the tree's own) is
+    removed with `git worktree remove` and pruned. Its branch is kept. Any
+    other tree is moved, as `work/` is retained, to
+    `<deployment>/.agents/worktrees/<repo>/<branch>`.
+  - A locked tree refuses the retire with `E_WORK_PRESERVATION_FAILED`
+    before anything runs: no session is stopped and no retire hook runs. A
+    move or removal Git refuses refuses it after the hooks. Either way the
+    home is kept. `--force` does not bypass it, and `--discard-worktree` does
+    not apply to extra trees.
+  - With `--keep-dir`, or when the home is kept for a retry, the trees stay
+    where they are.
+
+  `oats retire <instance> --plan` adds `facts.extraWorktrees` (`[{path, repo,
+  branch, detachedAt, disposition, movedTo, reason}]`, empty when there are
+  none) and one `notes` string per tree. The trees are part of
+  `planRevision`: a tree created, removed, dirtied or cleaned between the plan
+  and the apply refuses the apply with `E_PLAN_STALE`. The retire receipt adds
+  `extraWorktrees` (the plan's row plus `outcome`), present when a tree was
+  handled. The `worktree-removed` and `worktree-retained` events for an extra
+  tree carry `extra: true` and its `path`. All keys are additive. See
+  [souls and instances](../souls-and-instances.md#extra-trees-at-retire) and
+  [the CLI API](../desktop-cli-api.md#retire).
+
+## Fixed
+
+- **The context panel shows the soul and teams of an instance on a server**
+  ([#675](https://github.com/awebai/oats/issues/675)). The Soul tab and the
+  Messaging & Teams list were empty for an instance on a registered server.
+  They now read through the server by the instance's home, as the soul page
+  does, and say "Reading from <server>…" while they wait. The Soul tab's
+  header shows the soul's description from the server's roster. The Work
+  card, the "model from" line and the "older build" chip show the facts the
+  server relays. When a part can't be shown, it says why and what to update:
+  this computer's OATS when it can't route the read or doesn't relay the
+  facts, the server's OATS when it lacks the feature or doesn't report them.
+  A server's other refusals show its code and message, as the rest of the
+  panel does.

package/docs/servers.md

@@ -300,7 +300,10 @@ before 0.36.0, `null` when it reports none or the probe failed), the remote soul
 the host's own facts from its `status --json`: `identity`,
 `identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
 `runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
-`relativeTo` and `spawnOrigin`. A fact the host does not supply is `null`
+`relativeTo`, `spawnOrigin`, and (0.42.1) `work`, `repo`, `branch`,
+`modelFrom`, `soul` and `modules`: the local row's facts, with `soul` and
+`modules` the host's own drift observation, never recomputed here, and
+`repo` a path on the host. A fact the host does not supply is `null`
 (an older host, or a saved route the host no longer lists). A row also
 carries `waitingOnYou` (needs input) when the host's kernel reports it, and
 only then: an older host's row has no such key. A removed or edited registration keeps

package/docs/souls-and-instances.md

@@ -809,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
@@ -824,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
@@ -863,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
 
@@ -880,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
 
@@ -935,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.

package/lib/core.mjs

@@ -71,7 +71,7 @@ export { exactTreeDigest, fingerprintTree, KERNEL_HOME_RECEIPTS };
 import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
 import { readPortableBytes } from "./bounded-read.mjs";
 import { copyTreeSafe } from "./tree-copy.mjs";
-import { assertSameWorktreeHead, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
+import { assertSameWorktreeHead, gitRead, gitRepoRead, gitRepoRun, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
 /** The package and capability id grammar (namespaced, lowercase): an id names a
  *  directory (a home's module copy), so no path spelling fits it. */
 const PACKAGE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
@@ -5141,18 +5141,123 @@ function baselineDisposableHome(baseline) {
  *  that pass all use this one set. → { excludeRoot: Set (work/ and the covered
  *  names), notCopied: [{ scope: "home", path, owner }] sorted by path }: names
  *  and owners only. Two owners of one entry: the first in owner order. */
-function resolveHomeExclusions(home, disposableHome = []) {
+function resolveHomeExclusions(home, disposableHome = [], extraTrees = []) {
   const excludeRoot = new Set(["work"]);
   const notCopied = [];
-  if (!disposableHome.length) return { excludeRoot, notCopied };
+  const extra = new Set(extraTrees.map((t) => t.name));
+  if (!disposableHome.length && !extra.size) return { excludeRoot, notCopied };
   for (const name of readdirSync(home).sort(byCodeUnit)) {
-    const row = name === "work" ? undefined : disposableHome.find((r) => disposableHomeRootMatches(r.root, name));
-    if (!row) continue;
+    const owner = extra.has(name) ? EXTRA_WORKTREE_OWNER : name === "work" ? undefined : disposableHome.find((r) => disposableHomeRootMatches(r.root, name))?.owner;
+    if (!owner) continue;
     excludeRoot.add(name);
-    notCopied.push({ scope: "home", path: name, owner: row.owner });
+    notCopied.push({ scope: "home", path: name, owner });
   }
   return { excludeRoot, notCopied };
 }
+
+/** The `notCopied` owner of a verified extra tree: the retire's extra-tree
+ *  step handles it, not the home recovery. */
+const EXTRA_WORKTREE_OWNER = "kernel:extra-worktree";
+/** `git worktree list --porcelain -z` → [{ worktree, locked }]: `locked` is
+ *  the lock's reason ("" when it gives none), undefined when not locked. */
+function parseWorktreeList(out) {
+  const records = [];
+  for (const field of out.split("\0")) {
+    if (field.startsWith("worktree ")) records.push({ worktree: field.slice("worktree ".length) });
+    else if (records.length && (field === "locked" || field.startsWith("locked "))) records.at(-1).locked = field.slice("locked ".length);
+  }
+  return records;
+}
+/** The home's extra trees (awebai/oats#674), in every work mode: top-level
+ *  entries named `.work-*` that are real directories (not symlinks), whose
+ *  `.git` is a regular file, and that Git confirms are registered linked
+ *  worktrees of a repository outside the home: the git dir differs from the
+ *  common dir, the toplevel is the entry, and the repository's worktree list
+ *  names it. The repository is that list's first entry (its main worktree, or
+ *  the bare dir), as for the primary checkout (canonicalDeploymentPath).
+ *  Anything else named `.work-*` is ordinary home bytes. Read-only probes
+ *  (gitRead). → [{ name, path, repo, gitDir, commonDir, locked }] sorted by
+ *  name: `commonDir` is the repository's Git directory, which the step and
+ *  the reachability read name it by (bare or not). */
+function extraWorktreesOf(home) {
+  const trees = [];
+  let names;
+  try { names = readdirSync(home); } catch { return trees; }
+  const realHome = realPathOrNearest(home);
+  const inHome = (p) => { const rel = relative(realHome, realPathOrNearest(p)); return rel === "" || !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)); };
+  for (const name of names.sort(byCodeUnit)) {
+    if (!name.startsWith(".work-")) continue;
+    const path = join(home, name);
+    try {
+      if (!lstatSync(path).isDirectory() || !lstatSync(join(path, ".git")).isFile()) continue;
+    } catch { continue; }
+    const dirs = gitRead(path, ["rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir", "--show-toplevel"]);
+    if (!dirs.ok) continue;
+    const [gitDir, commonDir, toplevel] = dirs.out.split("\n");
+    if (!gitDir || !commonDir || !toplevel || realPathOrNearest(gitDir) === realPathOrNearest(commonDir)) continue;
+    const real = realPathOrNearest(path);
+    // A repository inside the home goes with the home: its trees are home bytes.
+    if (realPathOrNearest(toplevel) !== real || inHome(commonDir)) continue;
+    const list = gitRead(path, ["worktree", "list", "--porcelain", "-z"]);
+    if (!list.ok) continue;
+    const records = parseWorktreeList(list.out);
+    const self = records.find((r) => realPathOrNearest(r.worktree) === real);
+    if (!records.length || !self) continue;
+    trees.push({ name, path, repo: records[0].worktree, gitDir, commonDir: realPathOrNearest(commonDir), locked: self.locked });
+  }
+  return trees;
+}
+/** Where a retired worktree is re-homed: `<workspace>/.agents/worktrees/<repoName>/<leaf>`,
+ *  the leaf being the branch, else `detached-<commit>`; when that exists (or
+ *  `taken` holds it), `<leaf>-2`, `-3`, … The one naming rule of work/ and of
+ *  the extra trees. Creates nothing. */
+function retainedWorktreeDest(workspace, repo, branch, commit, taken = new Set()) {
+  const repoName = basename(realPathOrNearest(repo)).replace(/\.git$/, "") || "repo";
+  const leaf = (branch ?? `detached-${(commit || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
+  const retainedRoot = join(workspace, ".agents", "worktrees", repoName);
+  let dest = join(retainedRoot, leaf);
+  for (let n = 2; existsSync(dest) || taken.has(dest); n++) dest = join(retainedRoot, `${leaf}-${n}`);
+  taken.add(dest);
+  return dest;
+}
+/** What retirement does with each extra tree (`trees`: extraWorktreesOf) →
+ *  [{ path, repo, branch, detachedAt, disposition, movedTo, reason }], one row
+ *  per tree in order: the retire plan's `extraWorktrees` and the binding the
+ *  retire checks before it acts. `remove` when the tree is clean: an empty
+ *  status (ignored and untracked files count), no operation in progress, and
+ *  a HEAD commit some ref of the repository reaches: its shared refs, never
+ *  the tree's own HEAD, reflog or refs/worktree/, which go with its admin
+ *  entry when it is removed. `retain` (to `movedTo`) otherwise, with why
+ *  in `reason`; a HEAD that cannot be read is not clean. `refuse` for a locked
+ *  tree, which Git will neither move nor remove. Read-only. */
+function extraWorktreeRows(trees, root) {
+  const taken = new Set();
+  return trees.map((tree) => {
+    let name = null, commit = null;
+    try { name = headName(tree.path); } catch { /* not clean, below */ }
+    try { commit = worktreeHead(tree.path).commit; } catch { /* not clean, below */ }
+    const row = { path: tree.path, repo: tree.repo, branch: name?.branch ?? null, detachedAt: name?.detached ? commit : null, disposition: "remove", movedTo: null, reason: null };
+    if (tree.locked !== undefined) return { ...row, disposition: "refuse", reason: `it is locked${tree.locked ? ` (${tree.locked})` : ""}; unlock it with \`git worktree unlock\`, or move it out of the home, then retire again` };
+    const why = [];
+    if (!name || !commit) why.push("its HEAD could not be read");
+    const status = gitRead(tree.path, ["status", "--porcelain", "-z", "--ignored", "--untracked-files=all", "--ignore-submodules=none"]);
+    if (!status.ok) why.push(`its status could not be read (${status.err})`);
+    else if (status.out.length) why.push("it holds uncommitted, untracked or ignored files");
+    if (RECOVERABLE_GIT_ADMIN.some((n) => existsSync(join(tree.gitDir, n)))) why.push("an operation is in progress in it");
+    if (commit) {
+      const reach = gitRepoRead(tree.commonDir, ["for-each-ref", "--contains", commit, "--count=1", "--format=%(objectname)"]);
+      if (!reach.ok) why.push(`which refs reach its HEAD commit could not be read (${reach.err})`);
+      else if (!reach.out.length) why.push("its HEAD commit is reached by no ref");
+    }
+    if (!why.length) return row;
+    return { ...row, disposition: "retain", movedTo: retainedWorktreeDest(workspaceOf(root), tree.repo, row.branch, commit, taken), reason: why.join("; ") };
+  });
+}
+/** The retire plan's view of a home's extra trees: extraWorktreeRows of what
+ *  is there now. */
+export function extraWorktreePlan(home, root) {
+  return extraWorktreeRows(extraWorktreesOf(home), root);
+}
 function unionNotCopied(...lists) {
   const byPath = new Map();
   for (const row of lists.flatMap((list) => list || [])) if (!byPath.has(row.path)) byPath.set(row.path, row);
@@ -6414,9 +6519,11 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
   }
   const baselineValid = retirementBaselineValid(baseline, home);
   // This pass's one resolved exclusion set: provider-owned entries the spawn
-  // baseline declared. Every home fingerprint here and the copy made from this
-  // observation use it; without a valid baseline there is none.
-  const homeExclusions = resolveHomeExclusions(home, baselineValid ? baselineDisposableHome(baseline) : []);
+  // baseline declared, and the home's verified extra trees (whatever the
+  // baseline), which the retire's extra-tree step handles from this same set.
+  // Every home fingerprint here and the copy made from this observation use it.
+  const extraTrees = extraWorktreesOf(home);
+  const homeExclusions = resolveHomeExclusions(home, baselineValid ? baselineDisposableHome(baseline) : [], extraTrees);
   // One walk of the home, two digests: the stored one for the comparison with
   // the baseline, which must not see the kernel's own fields of instance.json,
   // and the exact one for the comparison after the hooks, which must see
@@ -6504,7 +6611,7 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
     .update("\0").update(unreached ? `${unreached.head.commit}\0${unreached.unreached ? "unreached" : "reached"}\0` : "")
     .update(unreached?.head.ref ?? "")
     .digest("hex");
-  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
+  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, extraTrees, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
 }
 
 function copyRecoveryTree(src, dest, { excludeRoot = new Set() } = {}) {
@@ -7020,7 +7127,8 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
   const intent = {
     instance: name, agent: found.agent.name, root: resolve(root),
     requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
-    options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session }, resultPath,
+    // A confirmed plan's extra trees go with the intent, so the completion is bound by them as well.
+    options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}) }, resultPath,
   };
   const env = { ...process.env, OATS_RETIRE_INTENT: JSON.stringify(intent) };
   for (const k of CORE_LAUNCH_ENV) delete env[k];
@@ -7098,6 +7206,7 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
   try {
     result = retireInstance(intent.root, intent.instance, {
       home: intent.options?.home, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
+      ...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
       ...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
     });
   } catch (e) {
@@ -7241,6 +7350,16 @@ export function retireInstance(root, name, o = {}) {
   // Whether this retire removes the worktree, when it gets to that step.
   const worktreeRemoval = { removes: !!(o.discardWorktree || owesWorktree), repo: meta.repo };
   const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
+  // A locked extra tree is known from the home as it is now: Git will neither move nor remove it, so a retire that
+  // would remove the home refuses here, before the session is stopped and before any retire hook runs (the hooks
+  // revoke identities a kept home would still need). The extra-tree step keeps its own check, for a lock that appears
+  // during the hooks. --force does not bypass it: it covers hook debt, not local work.
+  if (!o.keepDir) {
+    const locked = initialObservation.extraTrees.filter((t) => t.locked !== undefined);
+    if (locked.length) {
+      throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: ${locked.map((t) => `the extra worktree ${t.path} is locked${t.locked ? ` (${t.locked})` : ""}`).join("; ")}; Git will neither move nor remove a locked worktree. Unlock it with \`git worktree unlock\`, or move it out of the home, then retire again; nothing was run or removed`);
+    }
+  }
   // Harness identity is destructive authority. The mutable child metadata may
   // describe it for humans, but only the independent baseline can authorize the
   // endpoint that proves quiescence.
@@ -7484,6 +7603,54 @@ export function retireInstance(root, name, o = {}) {
   // A failed spawn's quarantine that owes the worktree removes it; any other retire retains it unless
   // --discard-worktree. An orphaned work directory is never touched.
   const outstandingBeforeWorktree = quarantine ? retryFailures : ordinaryIncomplete;
+  // The home's extra trees (awebai/oats#674), in every work mode, before the
+  // work/ step so that a refusal here leaves work/ as it is. Only when the
+  // home is going to be removed: not under --keep-dir, and not when it is
+  // kept for a retry (the work/ step's condition). The trees are the final
+  // inspection's verified set, the one its recovery left out of the home's
+  // bytes. A clean tree is removed (its branch stays in its repository); any
+  // other is re-homed like work/; a locked one, or one Git will not move or
+  // remove, refuses and keeps the home, --force included: it covers hook
+  // debt, not local work. --discard-worktree does not apply. An applied plan
+  // (`plannedExtraWorktrees`) binds what is done: trees that no longer read
+  // as planned refuse as stale before any of them is touched.
+  let extraWorktrees;
+  if (!o.keepDir && !(outstandingBeforeWorktree.length > 0 && !o.force)) {
+    const rows = extraWorktreeRows(finalObservation.extraTrees, root);
+    if (o.plannedExtraWorktrees && JSON.stringify(rows) !== JSON.stringify(o.plannedExtraWorktrees)) {
+      throw oatsError("E_PLAN_STALE", `${name}: the home's extra worktrees changed since the retire plan was shown, so none of them was moved or removed. The retire hooks have run; the home and its work are kept. Review the fresh plan (\`oats retire ${name} --plan\`) and apply it again.`);
+    }
+    const refused = rows.filter((r) => r.disposition === "refuse");
+    if (refused.length) {
+      throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: ${refused.map((r) => `the extra worktree ${r.path}: ${r.reason}`).join("; ")}. No extra worktree was moved or removed and work/ is untouched; the retire hooks have run and the home is kept so nothing is lost.`);
+    }
+    extraWorktrees = [];
+    const done = () => extraWorktrees.length ? ` Already done in this retire: ${extraWorktrees.map((r) => r.outcome === "removed" ? `${r.path} removed` : `${r.path} re-homed to ${r.movedTo}`).join(", ")}.` : "";
+    // Each row's repository, by its Git directory: the commands run helper-free (gitRepoRun).
+    const gitDirOf = new Map(finalObservation.extraTrees.map((tree) => [tree.path, tree.commonDir]));
+    const git = (row, argv) => gitRepoRun(gitDirOf.get(row.path), argv);
+    const failed = (row, what, e) => oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the extra worktree ${row.path} ${what} (${String(e?.stderr ?? e?.message ?? e ?? "").trim()}).${done()} work/ is untouched; the retire hooks have run and the home is kept so nothing is lost — resolve and retry.`);
+    for (const row of rows) {
+      if (row.disposition === "remove") {
+        try {
+          git(row, ["worktree", "remove", row.path]);
+          git(row, ["worktree", "prune"]);
+          const real = realPathOrNearest(row.path);
+          if (existsSync(row.path) || parseWorktreeList(git(row, ["worktree", "list", "--porcelain", "-z"])).some((r) => realPathOrNearest(r.worktree) === real)) throw new Error("it is still there after `git worktree remove`");
+        } catch (e) { throw failed(row, "could not be removed, or its removal could not be verified", e); }
+        extraWorktrees.push({ ...row, outcome: "removed" });
+        appendEvent(found.home, { kind: "worktree-removed", data: { branch: row.branch, extra: true, path: row.path } }, { workspaceOnly: true });
+      } else {
+        try {
+          mkdirSync(dirname(row.movedTo), { recursive: true });
+          git(row, ["worktree", "move", row.path, row.movedTo]);
+        } catch (e) { throw failed(row, `could not be re-homed to ${row.movedTo}`, e); }
+        extraWorktrees.push({ ...row, outcome: "retained" });
+        appendEvent(found.home, { kind: "worktree-retained", data: { movedTo: row.movedTo, branch: row.branch, recordedBranch: null, extra: true, path: row.path } }, { workspaceOnly: true });
+      }
+    }
+    if (!extraWorktrees.length) extraWorktrees = undefined;
+  }
   const worktreeStep = isWorktree && !!meta.repo && !orphanedWork;
   const worktreeDeferred = worktreeStep && existsSync(workPath) && outstandingBeforeWorktree.length > 0 && !o.force;
   const keptForRetry = worktreeDeferred ? `git worktree ${workPath}: kept for the retry; outstanding: ${outstandingBeforeWorktree.join("; ")}` : null;
@@ -7507,12 +7674,8 @@ export function retireInstance(root, name, o = {}) {
       shTry(`git -C ${shq(meta.repo)} worktree prune`);
       retention = { worktree: "removed", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
     } else if (existsSync(workPath)) {
-      const repoName = basename(realPathOrNearest(meta.repo)).replace(/\.git$/, "") || "repo";
-      const leaf = (verifiedBranch ?? `detached-${(ref.commit || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
-      const retainedRoot = join(workspaceOf(root), ".agents", "worktrees", repoName);
-      mkdirSync(retainedRoot, { recursive: true });
-      let dest = join(retainedRoot, leaf);
-      for (let n = 2; existsSync(dest); n++) dest = join(retainedRoot, `${leaf}-${n}`);
+      const dest = retainedWorktreeDest(workspaceOf(root), meta.repo, verifiedBranch, ref.commit);
+      mkdirSync(dirname(dest), { recursive: true });
       try {
         execFileSync("git", ["-C", meta.repo, "worktree", "move", workPath, dest], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
       } catch (e) {
@@ -7623,7 +7786,7 @@ export function retireInstance(root, name, o = {}) {
     rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
   }
 
-  const result = { retired: name, agent: found.agent.name, workRecovery, retention, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
+  const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
     const w = [...(hookResults?.warnings || [])];
     if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
     if (isCapturedHome(meta) && !quarantine) {

package/lib/instance-git.mjs

@@ -43,6 +43,28 @@ function git(cwd, argv, { allowFail = false, input, diffExit = false } = {}) {
   }
 }
 const trim = (s) => (s === null ? null : s.trim());
+/** One helper-free Git probe run like the module's other reads
+ *  (READ_ONLY_GIT, gitEnv, argv, no shell) → { ok, out, err }. `out` is text.
+ *  Never throws: the caller decides what a failure means. `cwd`: the tree
+ *  `-C` names; gitRepoRead names the repository by its Git directory instead. */
+export function gitRead(cwd, argv) { return gitProbe(["-C", cwd], argv); }
+/** gitRead against the repository whose (common) Git directory is `gitDir`,
+ *  named explicitly (`--git-dir`), so that a bare repository is read too
+ *  (READ_ONLY_GIT sets safe.bareRepository=explicit). */
+export function gitRepoRead(gitDir, argv) { return gitProbe(["--git-dir", gitDir], argv); }
+/** A Git command that changes the repository whose Git directory is `gitDir`
+ *  (a worktree move, remove or prune), under the same discipline as the
+ *  reads: the repository's own configuration names no helper that runs
+ *  (fsmonitor, hooks, external diff; they reach the commands Git starts for
+ *  it through GIT_CONFIG_PARAMETERS), and nothing of the caller's Git
+ *  environment is passed. → stdout; throws the error execFileSync throws. */
+export function gitRepoRun(gitDir, argv) {
+  return execFileSync("git", ["--git-dir", gitDir, ...READ_ONLY_GIT, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 120_000, env: gitEnv() });
+}
+function gitProbe(where, argv) {
+  const r = spawnSync("git", [...where, ...READ_ONLY_GIT, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
+  return !r.error && r.status === 0 ? { ok: true, out: r.stdout } : { ok: false, out: "", err: String(r.error?.message ?? r.stderr ?? "").trim() || `git ${argv[0]} exited with ${r.status}` };
+}
 
 const BRANCH_REFS = Buffer.from("refs/heads/");
 /** The two reads of HEAD, as bytes. They run like the module's other reads:

package/lib/instance-lifecycle.mjs

@@ -10,7 +10,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, retirementRecoveryFacts, stopInstanceSession } from "./core.mjs";
+import { extraWorktreePlan, findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, retirementRecoveryFacts, stopInstanceSession } from "./core.mjs";
 import { groupedByOwner } from "./retire-output.mjs";
 import { observeInstanceGit } from "./instance-git.mjs";
 import { appendEvent } from "./instance-events.mjs";
@@ -165,6 +165,13 @@ function writeFileSyncAtomic(path, value) {
   writeFileSync(tmp, JSON.stringify(value, null, 2)); renameSync(tmp, path);
 }
 
+/** A retire plan's note for one extra tree (core extraWorktreePlan row). */
+function extraWorktreeNote(t) {
+  const at = t.branch ? `branch ${t.branch}` : t.detachedAt ? `detached at ${t.detachedAt.slice(0, 12)}` : "a HEAD that could not be read";
+  if (t.disposition === "remove") return `extra worktree ${t.path} (${at}) is clean and would be removed; its branch and commits stay in ${t.repo}`;
+  if (t.disposition === "retain") return `extra worktree ${t.path} (${at}) would be re-homed to ${t.movedTo}: ${t.reason}`;
+  return `extra worktree ${t.path} (${at}): retire refuses, ${t.reason}`;
+}
 /** How many declared roots a retire plan's recovery note lists before `, and N more`. */
 const PLAN_NOT_COPIED_CAP = 16;
 /** Facts for Remove (retire): what retirement would touch, with the design's
@@ -178,12 +185,19 @@ export function planRetire(ctx, root, name, { home } = {}) {
   const target = targetFacts({ ...me, instance: name, depth: 0 });
   target.session = retireSessionFacts(me.home, target.session);
   const meta = readJson(join(me.home, "instance.json")) || {};
+  // The home's extra trees and what retire does with each: listed, and bound
+  // into the revision (below), so that an apply refuses as stale when a tree
+  // was created, removed, dirtied or cleaned, or its target was taken.
+  const extraWorktrees = extraWorktreePlan(me.home, me.root);
   const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, repo: meta.repo ?? null, recordedBranch: meta.branch ?? null,
+    extraWorktrees,
     children: kids.map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, session: sessionFacts(c.home) })),
     ambiguous: (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason })),
     pullRequest: "unknown" /* forge facts are the ADE's (P1); the kernel never claims 'no PR' */ };
   const defaults = { retainWorktree: meta.work === "worktree", deleteBranch: false, stopChildren: true, retainChildren: true };
-  const safety = [me.home, target.session.state, target.launched, facts.work.observed ? [facts.work.revision, facts.work.branch, facts.work.changed, facts.work.untracked] : null, kids.map((c) => c.home)];
+  const safety = [me.home, target.session.state, target.launched, facts.work.observed ? [facts.work.revision, facts.work.branch, facts.work.changed, facts.work.untracked] : null, kids.map((c) => c.home),
+    // Only when there are any: a home without extra trees keeps the revision it had.
+    ...(extraWorktrees.length ? [extraWorktrees] : [])];
   // What retire would preserve and where, read from the spawn baseline and the
   // work mode: nothing is hashed, and the plan revision does not depend on it.
   // The declared roots are listed as written, capped so one note stays short.
@@ -195,6 +209,7 @@ export function planRetire(ctx, root, name, { home } = {}) {
     notes: [
       ...(facts.work.observed && facts.work.drift ? [`the worktree is on ${facts.work.branch ?? (facts.work.detached ? "a detached HEAD" : "a ref OATS carries no branch name for")}, not the recorded ${facts.recordedBranch}`] : []),
       ...(facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
+      ...extraWorktrees.map(extraWorktreeNote),
       ...(kids.length ? [`${kids.length} recorded child instance(s) are stopped first (bounded SIGTERM, never escalated) and retained (their homes are not removed); a child still running after the grace refuses the retirement`] : []),
       ...((kids.ambiguous || []).length ? [`${kids.ambiguous.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),
       ...(target.session.note ? [target.session.established ? `session absent: ${target.session.note}; nothing needs quiescing` : `session not observably absent: ${target.session.note}; retire refuses until it is stopped`] : []),

package/lib/retire-output.mjs

@@ -1,6 +1,7 @@
 /** What `oats retire` says about the work it preserved. One function renders
  *  the lines for the local and the remote path of bin/oats.mjs, from the
- *  receipt's `workRecovery` (lib/core.mjs, retireInstance). A receipt from an
+ *  receipt's `workRecovery` (lib/core.mjs, retireInstance); another renders
+ *  its `extraWorktrees`. A receipt from an
  *  older kernel, or a stored one, may carry `workRecoveries[]` instead: one
  *  block is printed per entry. Dependency-free. */
 
@@ -48,3 +49,15 @@ export function workRecoveryLines(receipt, { host } = {}) {
   }
   return lines;
 }
+
+/** The lines `oats retire` prints for the home's extra trees it handled
+ *  (the receipt's `extraWorktrees`): one per tree, removed or re-homed. */
+export function extraWorktreeLines(receipt, { host } = {}) {
+  const rows = Array.isArray(receipt?.extraWorktrees) ? receipt.extraWorktrees : [];
+  return rows.map((t) => {
+    const at = t.branch ? `branch ${t.branch}` : t.detachedAt ? `detached at ${t.detachedAt}` : "a HEAD that could not be read";
+    return t.outcome === "removed"
+      ? `Extra worktree ${t.path} removed (${at}); its branch and commits stay in ${t.repo}${host ? ` on ${host}` : ""}`
+      : `Extra worktree ${t.path} re-homed${host ? ` on ${host}` : ""} to ${t.movedTo} (${at}): ${t.reason}`;
+  });
+}

package/lib/servers.mjs

@@ -783,8 +783,11 @@ function listSnapshotServers() {
  *  action authority. */
 /** The facts a remote row relays from the host's `status --json` row, as the
  *  host reported them; a fact the host does not supply is null, never
- *  derived here. */
-export const REMOTE_ROW_FACTS = ["identity", "identityAddress", "teams", "startedAt", "createdAt", "model", "runtimeState", "parentInstance", "siblingInstance", "relation", "relativeTo", "spawnOrigin"];
+ *  derived here. `work`, `repo`, `branch` and `modelFrom` are the host's own
+ *  record (`repo` is a path on the host, never read here); `soul` and `modules`
+ *  carry the host's drift observation against its own members and lock, not
+ *  recomputed here (#675). */
+export const REMOTE_ROW_FACTS = ["identity", "identityAddress", "teams", "startedAt", "createdAt", "model", "runtimeState", "parentInstance", "siblingInstance", "relation", "relativeTo", "spawnOrigin", "work", "repo", "branch", "modelFrom", "soul", "modules"];
 const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k, i[k] ?? null]));
 /** `waitingOnYou` (feature waiting-on-you) is relayed ONLY when the host's row has the
  *  key, so it is not one of REMOTE_ROW_FACTS: a host whose kernel predates the feature

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.42.0",
+  "version": "0.42.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",