@awebai/oats 0.41.1 → 0.42.1

package/bin/oats.mjs

@@ -53,6 +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 { 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";
@@ -155,15 +156,6 @@ const jsonFail = (code, message, details, exit = 1) => { console.log(JSON.string
 const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok: true, result, ...envelopeWarnings() })); };
 // Text mode (or a JSON answer printed before the read): the warning goes to stderr, never stdout.
 process.on("exit", () => { const w = runtimeNameWarning(); if (w && !warningDelivered) process.stderr.write(`oats: warning: ${w.message}\n`); });
-const formatBytes = (n) => n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(1)} GiB`;
-/** A retire recovery's copied outputs (untracked/ignored or directory work), named with their size. */
-function preservedOutputLines(recovery) {
-  const outputs = recovery?.outputs;
-  if (!outputs?.paths?.length) return [];
-  const shown = outputs.paths.slice(0, 8).map((p) => `${p.path} (${formatBytes(p.bytes)})`);
-  const more = outputs.paths.length > 8 ? `, and ${outputs.paths.length - 8} more` : "";
-  return [`  copied outputs: ${shown.join(", ")}${more} — ${formatBytes(outputs.bytes)} in total`];
-}
 
 function shortPath(p) {
   if (!p) return p;
@@ -2506,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
@@ -2516,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
@@ -2529,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 */ } }
@@ -2570,11 +2565,8 @@ function retireCmd() {
   console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
   // 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 recovery of r.workRecoveries || (r.workRecovery ? [r.workRecovery] : [])) {
-    console.log(`Work that was not committed has been preserved: ${recovery.classes.join(", ")}`);
-    console.log(`  ${recovery.path}${typeof recovery.bytes === "number" ? ` (${formatBytes(recovery.bytes)})` : ""}`);
-    for (const line of preservedOutputLines(recovery)) console.log(line);
-  }
+  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.");
 }
@@ -3725,11 +3717,8 @@ async function serverRouteCmd() {
       if (branch) console.error(branch);
     }
     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 recovery of r.workRecoveries || (r.workRecovery ? [r.workRecovery] : [])) {
-      console.log(`Work that was not committed has been preserved on ${target.sshHost}: ${(recovery.classes || []).join(", ")}`);
-      console.log(`  ${recovery.path}${typeof recovery.bytes === "number" ? ` (${formatBytes(recovery.bytes)})` : ""}`);
-      for (const line of preservedOutputLines(recovery)) console.log(line);
-    }
+    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/capabilities.md

@@ -59,7 +59,8 @@ A self-contained package has an `oats.json`:
   "hooks": {
     "spawn": "bin/team-chat-hook.mjs spawn",
     "retire": "bin/team-chat-hook.mjs retire"
-  }
+  },
+  "retirement": { "disposable": { "home": [".team-chat", ".team-chat-id-*"] } }
 }
 ```
 
@@ -153,7 +154,77 @@ A self-contained package has an `oats.json`:
   and nothing is silently dropped. Without `--force` that state fails closed with
   `E_UNIDENTIFIED_INSTANCE_HOME` rather than deleting whatever credentials the
   directory still holds; `--force` removes it and leaves any external state for
-  the operator to clean up by hand.
+  the operator to clean up by hand. Home entries declared in
+  `retirement.disposable.home` (below) go with the home: recovery holds no
+  copy of them.
+- `retirement.disposable` declares what retirement treats as the provider's
+  own state rather than the instance's work. It is a map with two optional
+  keys, `home` and `work`, each an array of strings.
+  - `home`: provider-owned state that is not the instance's work, left in
+    place until the home is removed, and not copied to recovery. The one
+    exception is the preservation of a failed spawn in directory mode, which
+    copies the whole home, declared entries included. Each entry
+    names top-level entries of the instance home:
+    - an exact hidden name, `^\.[A-Za-z0-9_][A-Za-z0-9._-]*$` (`.team-chat`);
+    - or a prefix, `^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$` (`.team-chat-id-*`),
+      meaning every top-level entry whose name starts with the text before
+      `*`.
+
+    Refused:
+    - anything that is not one hidden top-level name (`notes`, `.aw/keys`,
+      `.a*`);
+    - an exact name that is `.oats`, `.agents` or `.claude`, or that starts
+      with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
+      `.oats-agents-md`, `.oats-start` or `.oats-attachments`: the top-level
+      entries the kernel itself writes in an instance home;
+    - a prefix that starts with `.oats-`.
+
+    An exact name such as `.oats-aweb` is allowed: it is a provider's
+    directory. Entries are matched by name, without following symlinks: a
+    declared entry that is a symlink is left out and never followed.
+
+    A matching entry is left out of the home fingerprint that retire compares
+    with the spawn baseline, of the home copy and of that copy's
+    verification, before and after the retire hooks. A change to declared
+    entries alone is therefore not "changed instance-home bytes" and causes
+    no copy. When a recovery is written, its receipt names what was left out
+    in `workRecovery.notCopied` (names and owners only).
+
+    The declaration is recorded at spawn, with its owner, in the home's
+    retirement baseline, and retire reads it from there only: never from the
+    module copy in the home, from the capability as it is today, or from
+    `instance.json`. A running instance is unaffected until it is respawned,
+    and a home spawned before its capability declared the entries gains no
+    exclusion from a package update: its home is copied whole. A missing or
+    invalid baseline means no exclusions either.
+
+    Exclusion means "not copied" and nothing more. Nothing is removed early:
+    the entries stay in the home until the home is removed, and retire hooks
+    still see them. An incomplete cleanup, or a copy or verification that
+    fails, keeps the home with them. A capability that declares nothing has
+    its home state copied with the rest of the home.
+  - `work`: relative roots under `work/` that the capability generates. In
+    worktree mode the roots are kept out of the "untracked or ignored
+    worktree bytes" class, so untracked or ignored bytes under them alone do
+    not cause a recovery. They are still copied when a copy is made. Like
+    `home`, the roots are recorded at spawn. The other work modes do not use
+    them.
+
+  A malformed `retirement` is refused wherever the manifest is read: member
+  discovery (`E_WORKSPACE_SCHEMA`), package manifests (`E_PACKAGE_MANIFEST`)
+  and the kernel loader refuse the same manifest, with a JSON pointer:
+  `/retirement` (no `disposable` map, or a key other than `disposable`,
+  `home` and `work`), `/retirement/disposable/<scope>` (not an array of
+  strings) or `/retirement/disposable/home/<i>` (an entry outside the
+  grammar):
+
+  ```text
+  capability <id> manifest retirement.disposable.home entry "<value>" must name one hidden top-level home entry (".name", or ".prefix-*")
+  capability <id> manifest retirement.disposable.home entry "<value>" covers a kernel-owned home entry
+  ```
+
+  This kernel reads the field. What retire does with the entries is in
+  [souls-and-instances.md](souls-and-instances.md#retire).
 - `requires` declares what must exist before the capability works. Two kinds:
   - a **host command** (`command`), satisfied by a binary on `PATH`;
   - a **harness package** (`harness` + `package`, optionally `marketplace`),

package/docs/capability-manifest.schema.json

@@ -293,6 +293,44 @@
         "type": "string",
         "pattern": "^[A-Z][A-Z0-9]*_$"
       }
+    },
+    "retirement": {
+      "type": "object",
+      "description": "What retirement treats as the provider's own state rather than the instance's work.",
+      "required": ["disposable"],
+      "properties": {
+        "disposable": {
+          "type": "object",
+          "properties": {
+            "home": {
+              "type": "array",
+              "description": "Provider-owned state that is not the instance's work, left in place until the home is removed, and not copied to recovery (the preservation of a failed spawn in directory mode is the exception: it copies the whole home, declared entries included). Each entry names top-level entries of the instance home: one hidden name (.aw) or a prefix (.aweb-identity-*, every top-level name that starts with the text before the *). Recorded at spawn: a running instance is unaffected until it is respawned.",
+              "items": {
+                "type": "string",
+                "pattern": "^\\.[A-Za-z0-9_][A-Za-z0-9._-]*(?:-\\*)?$",
+                "not": {
+                  "description": "Home entries the kernel owns cannot be declared.",
+                  "anyOf": [
+                    {"pattern": "^\\.(?:oats|agents|claude)$"},
+                    {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments)"},
+                    {"pattern": "^\\.oats-.*\\*$"}
+                  ]
+                }
+              }
+            },
+            "work": {
+              "type": "array",
+              "description": "Relative roots under work/ that a worktree instance's capability generates. Their untracked or ignored bytes do not count as the instance's untracked or ignored worktree bytes; they are still copied when a recovery copy is made.",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

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; …"]}
 ```
@@ -2457,10 +2479,54 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
   `unestablished`, with a `note` saying why, and retire refuses with
   `E_RUNTIME_ENDPOINT_UNKNOWN`, `--force` included. `notes` repeats either
   case. Read an unknown `state` as not idle.
+- `notes` says what a retire would copy to recovery (0.42), in up to two
+  strings read from the home's retirement baseline and the work mode, without
+  hashing anything:
+
+  ```text
+  recovery: the home is copied to /w/agents/dev/instances/.oats-retirement/recovery before the home is removed, when it changed since spawn; not copied: .aw, .aweb-identity, .aweb-identity-*, .oats-aweb (oats.aweb)
+  recovery: uncommitted worktree state is copied there too
+  ```
+
+  The first is always present. Its `; not copied: …` tail is there only when
+  the baseline records declared home entries
+  (`retirement.disposable.home`): `not copied: <roots> (<capability>)`, the
+  roots as written in the manifest, in the order the baseline stores them
+  (sorted by capability, then root), one group per capability, groups
+  separated by `; `. At most 16 roots are listed, then `, and N more`.
+  The second is the line above in worktree mode, `recovery: work/ is copied
+  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
@@ -2472,8 +2538,12 @@ A first retire prints the **raw receipt**, not an envelope:
 {"retired":"dev-1","agent":"dev",
  "retention":{"worktree":"retained","movedTo":"/w/.agents/worktrees/one/feat-x","branch":"feat/x","detachedAt":null,"recordedBranch":"agents/dev-1"},
  "worktreeRemoved":false,"branchDeleted":false,"removedDir":true,
- "workRecovery":{"path":"/w/.agents/recovered/dev-1-20260928T111000Z","classes":["untracked"],"bytes":2048,
-                 "outputs":{"paths":[{"path":"notes.md","bytes":2048}],"bytes":2048}},
+ "workRecovery":{"path":"/w/agents/dev/instances/.oats-retirement/recovery/dev-1-AbC123",
+                 "classes":["changed instance-home bytes","untracked or ignored worktree bytes"],"bytes":48444211,
+                 "home":{"paths":[{"path":".oats/","bytes":874696},{"path":".agents/","bytes":141312},{"path":"notes/","bytes":2048},{"path":"STATE.md","bytes":512}],"bytes":1018568},
+                 "outputs":{"paths":[{"path":"scratch/","bytes":1258291},{"path":"note.txt","bytes":12}],"bytes":1258303},
+                 "notCopied":[{"scope":"home","path":".aw","owner":"oats.aweb"}],
+                 "afterHooks":{"home":true,"work":false}},
  "childrenStopped":[{"instance":"dev-1-child","home":"/w/agents/dev/instances/dev-1-child","ok":true,"stopped":false,"alreadyIdle":true}],
  "planRevision":"4e5f6a7b8c9d0e1f2a3b4c5d","idempotencyKey":"r1","replayed":false}
 ```
@@ -2512,9 +2582,84 @@ 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.
-- `workRecovery` (or `workRecoveries[]`): `{path, classes, bytes, outputs?,
-  repoCopy?}`; `outputs: {paths: [{path, bytes}], bytes}` names what was
-  copied beyond tracked state, largest first.
+- `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.
+  - `classes` is the union of the classes seen before and after the retire
+    hooks, in first-seen order. `bytes` covers the whole directory,
+    `after-hooks/` included.
+  - `home`, `outputs` and `repoCopy` describe the pre-hook snapshot (the
+    top-level `home/`, `repo/` or `work/`) and are not rewritten by the
+    post-hook pass. So `repoCopy.copied: false` (a home-only snapshot) can
+    appear with `afterHooks.work: true`: the repository copy is then under
+    `after-hooks/repo/` only. A recovery first written after the hooks (the
+    instance was clean before them) has no `after-hooks/`, and those keys
+    describe that one snapshot.
+  - `home`: `{paths: [{path, bytes}], bytes}`. The top-level entries of the
+    `home/` snapshot, largest first, a directory ending in `/`. Always
+    present when a recovery is written.
+  - `outputs`: `{paths: [{path, bytes}], bytes}` names what was copied
+    beyond tracked state, largest first.
+  - `notCopied`: `[{scope, path, owner}]`, sorted by `path`. The home
+    entries that existed at any point of the retire (before or after the
+    hooks) and were left out by a capability's `retirement.disposable.home`
+    declaration ([capabilities.md](capabilities.md#manifest)), by their real
+    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. 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
+    records included), and `after-hooks/repo/` (worktree mode) or
+    `after-hooks/work/` (directory mode) unless the work is proven unchanged
+    after the hooks: a directory by its bytes and bits, a worktree by its Git
+    state and the bytes and bits of its files
+    ([souls and instances](souls-and-instances.md#retire)). A worktree that
+    holds a repository is never proven unchanged: for it `work: true` says
+    that a work copy was made after the hooks, not that a hook changed the
+    work. `work` is also `true` when the pre-hook snapshot held the home
+    only and the work was copied for the first time after the hooks, moved
+    or not, because something beyond the home was there to preserve. The
+    home is not copied again because the work is.
+    Each part is whole and verified, not a delta, but `after-hooks/` is not
+    a complete picture of the instance after the hooks: with `home: false`
+    the recovery's home is the pre-hook one, and it holds the kernel's own
+    records (the event log, the stop and restart receipts, listed in
+    [souls and instances](souls-and-instances.md#retire)) as of then.
+    Present only when that directory was written.
+  - `workRecoveries` is no longer emitted. An older kernel on a server may
+    still send `workRecoveries[]` beside `workRecovery` (one `{path, classes,
+    bytes, outputs?, repoCopy?}` per recovery directory it wrote), so a
+    reader must keep accepting it. A kernel before 0.42 sends no `home`,
+    `notCopied` or `afterHooks`.
+  - `recovery.json` inside the directory stays `version: 1`. It carries
+    `phase` (`"before-hooks"`, then `"complete"` once the post-hook check has
+    concluded), `home` and, when they apply, `notCopied` and `afterHooks`.
+    `phase` is not in the receipt: a receipt is produced only once that check
+    has concluded. A retried retire writes its own recovery and its receipt
+    names only that one
+    ([souls-and-instances.md](souls-and-instances.md#retire)).
 - When they apply: `rollbackIncomplete` and `retainedHome` (cleanup
   incomplete, home kept, exit 1), `forcedIncomplete`, `relinked`,
   `capabilityMeta`, `warnings`, `wakeSchedulesRemoved`.
@@ -2534,8 +2679,11 @@ 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_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
+`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
 the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
 source, recovery}], total}}` (the first 10 paths). Usage errors are text on

package/docs/desktop.md

@@ -77,16 +77,26 @@ Opened from Finder or the Dock, an app inherits launchd's PATH
 the CLI's `#!/usr/bin/env node`. At startup the Desktop therefore runs your
 login shell once (`$SHELL -ilc`, 3 s timeout) and puts its PATH in front of
 the inherited one, so the CLI probe, every `oats` call, a CLI picked with
-**Choose oats…**, and the tmux server and terminals the Desktop starts all run
-with your shell's PATH. Only PATH is taken from the shell, never the rest of
-its environment. The shell is started with your environment, without what the
+**Choose oats…**, and the terminals the Desktop starts all run with your
+shell's PATH. Only PATH is taken from the shell, never the rest of its
+environment. The OATS tmux server is different: when a spawn or a start the
+Desktop runs has to start it, the CLI gives it your whole login environment,
+read from your login shell
+([execution-targets.md](execution-targets.md#the-servers-start-environment)),
+and falls back to the environment the Desktop gave the CLI (with this PATH)
+only when that cannot be read, saying so on stderr. The shell is started with your environment, without what the
 Desktop or its packaging added to its own (on the AppImage, the entries under
 its mount), like every other program the Desktop starts. If the shell fails, times out or prints no PATH, the
 inherited PATH stays: the backend's `/api/cli` reports `pathSource`
 (`login-shell` or `inherited`), `pathError` (why, or `null`) and
 `probePath` (the PATH the probe used), and the reason is logged at startup.
-A tmux server that was already running keeps its own environment; restart it
-if its sessions should get the new PATH, which ends its sessions: `tmux -L oats kill-server` for the OATS tmux server, where instances run, and `tmux kill-server` for your default server, where an instance started by an earlier kernel may still be.
+An agent's pane takes its tmux session's or server's PATH, whoever opens its
+window, and its harness is looked up there
+([execution-targets.md](execution-targets.md#the-servers-start-environment)):
+a window the Desktop opens on a server that already runs gets that server's
+PATH, not the Desktop's. A tmux server that was already running keeps its own
+environment; restart it if its sessions should get the new PATH, which ends
+its sessions: `tmux -L oats kill-server` for the OATS tmux server, where instances run, and `tmux kill-server` for your default server, where an instance started by an earlier kernel may still be.
 
 ## Opening a workspace
 
@@ -239,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>`).