@awebai/oats 0.41.0 → 0.42.0

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 { 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;
@@ -2570,11 +2562,7 @@ 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 w of r.warnings || []) console.log(`  WARNING: ${w}`);
   if (isSelf) console.log("This window dies in ~8s — say any goodbyes now.");
 }
@@ -3725,11 +3713,7 @@ 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);
     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

@@ -2457,6 +2457,25 @@ 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.
 
 Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
 (`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
@@ -2472,8 +2491,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 +2535,67 @@ 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.
+- `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. 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`.
@@ -2535,7 +2616,9 @@ A first retire prints the **raw receipt**, not an envelope:
 
 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`,
+`--discard-worktree`), `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