@awebai/oats 0.30.3 → 0.32.0

package/docs/configuration.md

@@ -34,6 +34,8 @@ souls:
 
 host:
   name: ana-laptop                           # which workspace triggers and schedules run here
+session:                                     # terminal defaults for NEW launches on this host (0.31)
+  tmuxSession: oats-agents                   # the tmux session new tmux instances open in
 triggers:
   disabled: [platform/nightly-review]
 schedules:
@@ -48,6 +50,11 @@ launch-configs:                              # named ways this host starts a har
       CLAUDE_CONFIG_DIR: { fromEnv: PERSONAL_CLAUDE_DIR }
     model: opus
     yolo: false
+  mine:
+    harness: claude
+    default: true                            # this host's baseline for every claude launch (0.32)
+    env:
+      CLAUDE_CONFIG_DIR: /home/ana/.claude-personal
 ```
 
 Schema: [`oats-local.schema.json`](oats-local.schema.json). Unknown keys are
@@ -64,10 +71,11 @@ refused (`E_WORKSPACE_SCHEMA`).
 | `souls.teams` | Which teams each soul joins here: `"*"` applies to every soul; a soul's own entry (its name, or `<package>/<soul>`) adds to it. Every soul is also in its default team. Written by `oats soul teams <soul>\|'*' --add … --remove …`. |
 | `souls.default` | A per-soul override of `defaultTeam`; it must be one of that soul's teams here (`E_TEAM_NOT_ELIGIBLE`). Written by `oats soul teams <soul> --default <label>`. |
 | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
+| `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
 | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
 | `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
 | `triggers.disabled`, `schedules.disabled` | Workspace triggers and schedules (`<member>/<id>`) this host does not run, without a commit. Written by `oats trigger disable` / `oats schedule disable`. |
-| `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. See [Launch configurations](#launch-configurations). |
+| `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. `default: true` makes it this host's baseline for its harness (0.32). See [Launch configurations](#launch-configurations). |
 | `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. See [Launch preferences](#launch-preferences). |
 
 How teams are resolved, and what a messaging provider does with them, is in
@@ -78,8 +86,9 @@ How teams are resolved, and what a messaging provider does with them, is in
 An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
 (a bare name looked up on `PATH`, or a path relative to this deployment
 directory), `args` (literal, no shell), `env` (a literal string, or
-`{ fromEnv: NAME }` resolved on the host at start), `model` and `yolo`. A
-launch configuration is a host choice: a soul never names one.
+`{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
+`default` (0.32; see [the harness default](#the-harness-default)). A launch
+configuration is a host choice: a soul never names one.
 
 - Select one with `--launch-config <name>` on `oats spawn`,
   `oats session start` and `oats session restart`. A named configuration is
@@ -101,6 +110,50 @@ launch configuration is a host choice: a soul never names one.
 - The old key `runtime` is still read as `harness`, with a
   `deprecated-runtime-name` warning.
 
+### The harness default
+
+`default: true` makes a configuration this host's baseline for its harness
+(0.32, feature `launch-config-default`). Use it for what every launch of a
+harness on this machine needs, whatever soul or preference chose it: an
+account directory (`CLAUDE_CONFIG_DIR`), a wrapper `executable`, an argument.
+
+- **When it applies:** a new launch that picks the harness without naming a
+  configuration: a soul's `launch:`, an inline `souls.launch` preference,
+  `--harness` (on a spawn, or on `session start|restart` of an existing
+  home), `--reselect-launch`, and the host default (`pi`). It supplies the
+  executable, args, env and `yolo`. A `yolo` recorded from a default stays
+  with it: a later `--launch-config none` or another harness does not carry
+  it over.
+- **The model** comes from whatever picked the harness (`--model`, then the
+  preference); the default's `model` is the last fallback, before the
+  harness's own.
+- **A named configuration runs as declared**: `--launch-config <name>` or a
+  `souls.launch` name never inherits from the default. `--launch-config none`
+  (or a `souls.launch` entry of `none`) asks for the bare harness and
+  bypasses it.
+- **One per harness.** A second `default: true` for the same harness is
+  refused (`E_LAUNCH_CONFIG_INVALID`, naming both); move it by clearing the
+  old one first.
+- **Existing homes keep their launch** until `--reselect-launch` or a
+  respawn, like any change of preference. Declaring a default is such a
+  change: `oats readiness --home` warns `launch-changed` on each existing
+  home the default would now apply to, until it is restarted with
+  `--reselect-launch` or respawned.
+- **It is visible.** `oats launch-config list` marks it; `spawn --preview`,
+  `launch-config preview`, `instance.json` and `oats inspect --home` say when
+  a launch's configuration came from the default (`launchConfigDefault`).
+  A default with `yolo: true` turns yolo on for every launch of that harness
+  here: the preview shows it.
+- **Every kernel that reads the deployment needs OATS 0.32+.** OATS 0.31
+  and older refuse the whole `oats-local.yaml` (`E_WORKSPACE_SCHEMA`) once a
+  configuration declares `default`.
+
+`oats-claude-config` (a one-line file naming the claude binary, found walking
+up from the deployment) is no longer read. A new claude launch with one in
+reach is refused (`E_CLAUDE_CONFIG_REMOVED`) naming the file: declare the
+name it holds as the claude default (`executable: <name>`, `default: true`)
+and delete the file. Homes launched with it keep their recorded executable.
+
 ### Launch preferences
 
 A soul says what its role should run on, and each machine may override it
@@ -125,9 +178,11 @@ souls:
   harness and replaces only its model.
 - A **launch configuration** name runs that configuration's full recipe. An
   **inline or soul preference** runs its harness the way this host starts it
-  without a configuration (the executable on `PATH`, no args, no env), with
-  its `model`. A preference without `model` uses the harness's own model; it
-  never borrows a lower layer's.
+  without a configuration: [the harness default](#the-harness-default) if
+  one is declared, else the executable on `PATH` with no args and no env,
+  with the preference's `model`. A preference without `model` uses the
+  harness default's model, else the harness's own; it never borrows a lower
+  layer's.
 - **A missing harness is refused**, never replaced: `E_HARNESS_UNAVAILABLE`
   names the layer that chose it and the fix (install the harness, or override
   it here in `souls.launch`). `oats souls` still lists the soul, with the
@@ -271,5 +326,10 @@ oats spawn <soul> --preview    # the exact modules, teams and provider payloads
 oats doctor                    # this deployment's files and the lock
 ```
 
-Environment: `OATS_REMOTE_CACHE` relocates the fetch cache;
-`OATS_PACKAGE_CATALOG` names an alternative package catalog file.
+Environment: `OATS_REMOTE_CACHE` relocates the fetch cache (which also holds
+the bounded parsed-read cache and the observations `--max-age` reuses; all of
+it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
+catalog file. The read verbs (`status`, `workspace status`, `souls`,
+`capabilities`, `inspect`, and the read forms of `teams` and `soul teams`)
+take `--max-age <seconds>` to reuse a remote head observed that recently
+([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)).

package/docs/desktop-cli-api.md

@@ -30,14 +30,15 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 
 ```json
 {"schemaVersion":1,"name":"@awebai/oats","version":"0.30.0","desktopApi":1,
- "harnesses":["pi","claude","codex"],"sessionBackends":["tmux","herdr"],"launchOptions":["yolo"],
- "remote":["spawn","retire","status","session","session-start","session-restart","launch-config","roster","harvest","schedule","session-upload","operations"],
+ "harnesses":["pi","claude","codex"],"sessionBackends":["tmux"],"launchOptions":["yolo"],
+ "remote":["spawn","retire","status","session","session-start","session-restart","launch-config","roster","harvest","schedule","session-upload","operations",
+           "readiness","instance-events","instance-git","lifecycle-plans"],
  "features":["retire-home","session-start","session-restart","launch-config","schedule","session-upload","operations","instance-git",
              "instance-git-remote","souls-declarations","lifecycle-plans","retire-retention","readiness","spawn-preview","instance-events",
              "instance-events-2","schedule-history","schedule-read-2","spawn-preview-2","spawn-idempotency","spawn-idempotency-2","spawn-apply-2",
              "workspace-v2","instance-modules","spawn-provider-payload","served-identity","packages-no-approval","spawn-name","settings-origins",
              "team-model-2","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
-             "preview-composed-from"],
+             "preview-composed-from","observe-max-age"],
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2}
 ```
@@ -47,10 +48,14 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
   accepted. The real gate is the feature list; its minimum is
   `packages-no-approval`.
 - `harnesses` is what `--harness` accepts; `sessionBackends` what `--backend`
-  accepts. A host without the `harness` feature lists `runtimes` instead.
+  accepts: `["tmux"]` since 0.31.0, when Herdr was removed (`--backend herdr`
+  is refused with `E_HERDR_REMOVED`). A host without the `harness` feature
+  lists `runtimes` instead.
 - `remote` is the routed surface: the commands `--server <id>` sends to a
   registered server, plus `roster`. The Desktop checks the execution host's
-  probe before a routed mutation.
+  probe before a routed mutation. From 0.31: `readiness`, `instance-events`,
+  `instance-git` and `lifecycle-plans` name the
+  [routed reads and plans](#routed-reads-and-plans).
 - In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
 
 ### Features
@@ -90,6 +95,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `desktop-facts` | the facts under [Desktop facts](#desktop-facts-feature-desktop-facts-oats-0290) | |
 | `launch-preference` | soul and local launch preferences; `launch`, `launchCurrent`, `launchFrom`; `--reselect-launch`; `key` on soul and agent rows ([Launch preferences](#soul-launch-preferences-feature-launch-preference-oats-0300)) | |
 | `preview-composed-from` | `composedFrom` on preview `modules[]` ([Composition](#the-preview)) | |
+| `observe-max-age` | `--max-age <s>` on the read verbs and their `observation` block ([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)) | |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -149,6 +155,20 @@ string for this: to support older kernels, use the spaced form.
 | `E_LOCAL_MISSING` | No `oats-local.yaml` in reach of `--dir` or the working directory |
 | `E_UNSUPPORTED_MODE` | A home or selector the kernel no longer runs (below) |
 
+<a id="ssh-failures-e_ssh"></a>
+### ssh failures (`E_SSH`)
+
+A routed command (`--server`, and `oats server check`) reports ssh's own
+failure as `E_SSH`, message `ssh to <host> failed: …`:
+
+- `error.details` is `{"sshStarted": false}` when ssh never started on this
+  machine (not installed, not executable): nothing reached the host, and
+  retrying cannot help.
+- No `details`: ssh ran and the link failed (unreachable host, refused key,
+  lost connection, timeout); a retry may succeed.
+
+(0.31.0; before it `E_SSH` never carried details.)
+
 Capability dispatch inside a home uses the home's module copies; from a
 deployment it resolves the module as `oats spawn --soul <x>` would and runs it
 with the soul's merged payload. `oats <namespace> --help --json` answers
@@ -162,6 +182,83 @@ an inherited `OATS_DEPLOYMENT` or `OATS_RESOLUTION` (`details.inherited`).
 homes in `problems[]`: `legacy-captured-home {code, instances, homes,
 message}` and `legacy-local-agents {code, dirs, instances, message}`.
 
+<a id="observation-reuse-feature-observe-max-age-oats-0311"></a>
+### Observation reuse (feature `observe-max-age`, OATS 0.32.0)
+
+Every read asks each remote for its current head (`git ls-remote`). With
+`--max-age <seconds>` a read verb reuses a head this machine observed at most
+that many seconds ago instead, so a refresh right after another costs no
+network round trip. Gate the flag on the feature: an older kernel may ignore
+it and answer live, without the block.
+
+```text
+oats status | workspace status | souls | capabilities | inspect --soul|--home
+     | teams | soul teams <soul>   … --max-age <seconds> --json
+```
+
+- **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
+  Anything else is `E_BAD_ARGS` (`--max-age needs a value: whole seconds from 0
+  to 86400`, `--max-age takes whole seconds from 0 to 86400, got "<v>"`).
+- **The block:** with the flag (`0` included) the document gains one key,
+  `observation: {observedAt, reused, localRevision}`: in the result of an
+  envelope, at the top level of the roster (after `agents`). `observedAt` is the
+  OLDEST remote head the answer used, so the answer is at least that fresh
+  everywhere; `reused` is `true` when any head came from an earlier observation.
+  A command that read no remote head reports the time it started and
+  `reused: false`. Without the flag the key is absent and every document is
+  exactly as before.
+- **`localRevision`:** 24 lowercase hex characters, opaque. It digests every
+  piece of local configuration the kernel read for this answer:
+  `oats-local.yaml` (and each closer `oats-local.yaml` it looked for and did
+  not find), `oats-lock.json`, an `OATS_PACKAGE_CATALOG` file, and the
+  automations snapshot. Only what the verb actually read counts. The same inputs
+  give the same revision; any byte change, or one of those files appearing or
+  disappearing, gives another. It names no path and no content. Different verbs
+  read different inputs (`workspace status` also reads the automations
+  snapshot; `inspect --home` reads no lock), so compare revisions of the same
+  verb and arguments only. Keep what you
+  hold (catalogs, inspect results) keyed on it: a different revision means the
+  deployment's configuration changed outside you (a `teams` edit, a sync, a
+  hand edit). A kernel upgrade shows through the probe (`oats version --json`),
+  not through `localRevision`: the bundled catalog is not an input. Instance
+  homes, member clones and tmux are not inputs either, because the answer
+  itself reports them.
+- **What is reused:** only remote heads (the commit a branch or tag named),
+  never local state. Instances, `oats-local.yaml` and the lock are read afresh
+  by every command. A member's backlink (`oats-membership.yaml`) is read at
+  the member's observed head, which may be a reused one: a backlink removed
+  less than `<s>` seconds ago can still show the member `confirmed` under
+  `--max-age <s>`. Only the backlink's comparison with this workspace is made
+  afresh. A reused head's
+  `observedAt` (for example `workspace.observedAt` in `workspace status`) is
+  the time it was observed, not now.
+- **When a head is not reused:** it is older than the flag allows (or dated
+  more than 5 s in the future); it was observed through a different URL
+  spelling of the same repository (ssh vs https) or for a different ref; its
+  commit can no longer be fetched. Each is observed live, as without the flag.
+  A live observation that fails is the usual error, never an older head.
+- **Refusals:** every other command, every edit form (`teams add|remove|default`,
+  `soul teams --add|--remove|--default|--clear-default`) and any `--server`
+  invocation refuse the flag before reading or writing anything, with
+  `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
+  verbs reuse observations (status, workspace status, souls, capabilities,
+  inspect --soul|--home, and the read forms of teams and soul teams)" and,
+  with `--server`, "--max-age cannot be combined with --server: observation
+  reuse is local to this machine".
+  A capability command's argv (`oats <namespace> …`) is its provider's: the
+  kernel neither reads nor refuses `--max-age` there. The same holds for
+  `capture`, `recall`, `setup` and `experimental`, which parse their own argv:
+  `capture`, `setup` and `experimental` refuse it as an unknown argument (not
+  `E_BAD_ARGS`), and `recall` ignores unknown flags.
+
+The observations are kept under the remote cache
+(`$OATS_REMOTE_CACHE`, default `~/.cache/oats/remotes`), in `.observed/`,
+beside the bounded parsed-read cache in `.parsed/`. An observation record
+keeps a digest of the fetch URL, never the URL. A parsed entry keeps repository
+content as committed (member refs included), and a value that carries a
+credential-bearing URL (userinfo on http(s), or `user:password@` on any
+scheme) is never written. Deleting either is always safe.
+
 <a id="inspect-readiness-and-operation-run-on-the-workspace-model-operationsapi-2-soulsapi-2-readinessapi-2-oats-0260"></a>
 ## Inspect, readiness and operation run
 
@@ -195,7 +292,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
 ### `oats inspect`
 
 ```text
-oats inspect (--home <abs> | --soul <name> [--dir <d>]) --json
+oats inspect (--home <abs> | --soul <name> [--dir <d>]) [--max-age <s>] --json
 ```
 
 An instance subject, abridged:
@@ -578,7 +675,7 @@ discovers the workspace over the network to check. Other errors: `E_USAGE`,
 ### `oats workspace status`
 
 ```text
-oats workspace status [--dir <d>] --json
+oats workspace status [--dir <d>] [--max-age <s>] --json
 ```
 
 Read-only (it writes no lock):
@@ -627,8 +724,8 @@ Read-only (it writes no lock):
 ### `oats capabilities` and `oats souls`
 
 ```text
-oats capabilities [--dir <d>] --json
-oats souls [--dir <d>] --json
+oats capabilities [--dir <d>] [--max-age <s>] --json
+oats souls [--dir <d>] [--max-age <s>] --json
 ```
 
 Every item of every confirmed member, the external souls, and the locked
@@ -816,7 +913,7 @@ soul subject), `""` when unknown.
 ### `oats teams`
 
 ```text
-oats teams [--dir <d>] --json
+oats teams [--dir <d>] [--max-age <s>] --json
 oats teams add <label> --team <id> [--description <d>] --json
 oats teams remove <label> --json
 oats teams default <label> --json
@@ -855,6 +952,7 @@ oats teams default <label> --json
 
 ```text
 oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <label> | --clear-default] [--dir <d>] --json
+oats soul teams <soul>|'*' [--dir <d>] [--max-age <s>] --json    (the read form only)
 ```
 
 ```json
@@ -1116,6 +1214,12 @@ it to a temporary copy (`soulFetched: true`).
   (absent when nothing sets it) are the resolved selection.
   `backendStatus` is `{name, installed, started: false}`, `null` with
   `--no-launch`. `executable` is the resolved harness binary.
+- `launchConfigDefault` (0.32, feature `launch-config-default`) is `true`
+  when `launchConfig` is this host's default for the harness (its
+  executable, args, env and `yolo` apply without being chosen), `false`
+  otherwise. Show it, and `yolo`, whenever it is `true`. An explicit
+  `--launch-config none` asks for the bare harness and bypasses the default;
+  to run the host's default, omit `--launch-config`.
 - `modelSource` is `"explicit"`, `"soul default"`, `"launch-config <name>"`,
   `"native default"` or `"native default (explicit)"` (`--model
   @native-default`). Omitting `--model` and asking for the native default are
@@ -1207,8 +1311,8 @@ with `--expect-decision` records the key and decision in `instance.json`.
 
 ```json
 {"instance":"rm-api","agent":"rm","home":"/w/agents/rm/instances/rm-api","work":"worktree","branch":"agents/rm-api","launched":true,"warnings":[],
- "tmux":{"session":"pi-agents","window":"rm-api"},"repo":"/w/agents-repo","harness":"pi","model":null,"parent":null,"sibling":null,"relation":null,
- "spawnOrigin":"operator","attach":"tmux attach -t pi-agents","decision":{"instance":"rm-api","revision":"c557d8ec9a272ba1c1739dc3"},"replayed":false,
+ "tmux":{"session":"oats-agents","window":"rm-api"},"backend":"tmux","repo":"/w/agents-repo","harness":"pi","model":null,"parent":null,"sibling":null,"relation":null,
+ "spawnOrigin":"operator","attach":"tmux attach -t oats-agents","decision":{"instance":"rm-api","revision":"c557d8ec9a272ba1c1739dc3"},"replayed":false,
  "wake":{"requested":false,"saved":null,"error":null},"launchConfig":null,
  "launch":{"version":2,"harness":"pi","launchConfig":null,"launchConfigSource":null,"executable":"/usr/local/bin/pi","executableDeclared":null,
            "executableResolvedFrom":"PATH","args":[],"env":{},"model":null,"hooks":{"launch":{},"env":{},"contributions":[]},"prompt":{"kind":"task-file","file":"TASK.md"}}}
@@ -1217,10 +1321,11 @@ with `--expect-decision` records the key and decision in `instance.json`.
 (`decision` is abridged: it is the full bound decision.)
 
 - Always present: `instance, agent, home, work, branch, launched, warnings
-  (array), tmux ({session, window} | null), repo, harness, model, parent,
+  (array), tmux ({session, window} | null), backend ("tmux"), repo, harness,
+  model, parent,
   sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
   launch` (the redacted recipe).
-- When they apply: `sessionTarget` (Herdr), `yolo`, `decision` and
+- When they apply: `yolo`, `decision` and
   `replayed` (bound apply), `wake` (keyed apply), `wakeSchedule` and
   `wakeScheduleError` (a requested wake).
 
@@ -1297,7 +1402,7 @@ workspace-model fields (feature `instance-modules`):
 ```
 
 Abridged: the record also carries the launch recipe and command,
-composition evidence, the capability runtime, the tmux or Herdr target,
+composition evidence, the capability runtime, the tmux target,
 lineage (`parentInstance`, `siblingInstance`, `relation`, `relativeTo`), and
 the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
 `wake`; later starts add `restarts` and `restartCount`.
@@ -1326,10 +1431,11 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
 ### The roster (`oats status --json`)
 
 ```text
-oats status [--dir <d>] --json
+oats status [--dir <d>] [--max-age <s>] --json
 ```
 
-Not an envelope: `{root, agents, workspace?, problems?, warnings?}`.
+Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}`
+(`observation` only with [`--max-age`](#observation-reuse-feature-observe-max-age-oats-0311)).
 
 ```json
 {"root":"/w/agents",
@@ -1354,8 +1460,13 @@ Not an envelope: `{root, agents, workspace?, problems?, warnings?}`.
   description, dir, instances}`.
 - **Instance rows**: the home's `instance.json` (launch recipe and command
   redacted) plus `home` and `instance` (from the directory; a disagreeing
-  claim is kept as `recordedHome`/`recordedInstance`), `running` (`null` when
-  a Herdr session is unreachable, with `runtimeState`/`runtimeError`),
+  claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
+  the row's recorded tmux socket and session, never the caller's `$TMUX`;
+  `null` with `runtimeState: "unreachable"` and the tmux error as
+  `runtimeError` when that server cannot be read; `null` for a home a
+  Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
+  `runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
+  in the row),
   `identity` when a provider recorded one, `rollbackIncomplete` and
   `retirePending` when present, and the Desktop facts below.
 - **`modules`** becomes drift rows `{name, from, commit, current, status,
@@ -1379,6 +1490,82 @@ restart, else `createdAt` for a launched home, else `null`. `modelFrom` is
 `"harness-default"`, or `null` for an older home. `identityAddress` is the
 messaging identity's `address` (else `alias`), or `null`.
 
+<a id="the-remote-roster-oats-server-roster---json"></a>
+### The remote roster (`oats server roster --json`)
+
+```text
+oats server roster [--server <id>] [--per-target <ms>] [--budget <ms>] --json
+```
+
+An envelope; `result` is `{groups, bounds}` (remote `roster`,
+[servers.md](servers.md#the-roster-and-harvest)). One group per server id and
+route target:
+
+```json
+{"id":"build:3f2a…","server":"build","label":"Build box","registrationPresent":true,
+ "target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},
+ "probe":{"ok":true},"agentsRoot":"/srv/team/agents",
+ "souls":[{"name":"dev","harness":"claude","work":"worktree","agentsRoot":"/srv/team/agents"}],
+ "instances":[{"server":"build","instance":"dev-a","agent":"dev","home":"/srv/team/agents/dev/instances/dev-a",
+               "agentsRoot":"/srv/team/agents","harness":"claude","backend":"tmux","tmux":{"session":"oats-agents","window":"dev-a"},
+               "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,
+               "savedRoute":false,"addressable":true,"missingRemotely":false}],
+ "retireFailures":[]}
+```
+
+- **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.
+- **`addressable`** (0.31): `true` for every row the host reports. Routed
+  session and lifecycle commands reach it by `--home`, or by name when the
+  name is unique on the host ([addressing](servers.md#run-there); a shared
+  name is `E_AMBIGUOUS` with `error.details.candidates: [{agent, home}]`). A
+  saved-route row the host did not list is addressable only while the host's
+  answer is unknown (`missingRemotely: false`).
+- **`savedRoute`**: the instance was spawned from this machine and has a
+  saved route here. Information only; no action depends on it.
+- `running` is `null` when unknown; `backend` is `tmux` for a row with a tmux
+  target, else `null`; `tmux`, `sessionTarget` (the recorded target of a home
+  a Herdr-era kernel opened) and `runtimeError` are as the host reports them.
+
+<a id="routed-reads-and-plans"></a>
+### Routed reads and plans (`--server`, 0.31)
+
+The Desktop's per-instance reads and the lifecycle plans run on the
+instance's own machine: the local command, with `--server <id>` added.
+
+| Command | `remote` entry | The host must advertise |
+|---|---|---|
+| `oats readiness --server <id> (--home <abs> \| --soul <n>) …` | `readiness` | `readiness`, `readinessApi: 2` |
+| `oats instance events <name> --server <id> …` | `instance-events` | `instance-events-2`, `eventsApi: 2` |
+| `oats instance git\|diff <name> --server <id> …` | `instance-git` | `instance-git`, `instanceGitApi: 1` |
+| `oats instance stop <name> --server <id> (--plan \| --apply …)` | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
+| `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
+
+- The flags are the local command's. The instance is addressed like every
+  routed instance command ([servers.md](servers.md#run-there)): `--home` as
+  given, else the name through its saved route or the host's roster, sent
+  as `--home`. `--dir` names a directory on the host and travels as is;
+  without it the registered workspace is sent (not for `readiness --home`,
+  whose home is its own context). A retire plan and its guarded apply take
+  `--dir` like the rest; an unguarded `retire --server` refuses it.
+- An instance with a saved route is reached through it, registration or not.
+  A guarded retire apply whose name the host no longer lists is sent by name,
+  so a repeated key gets the host's recorded receipt (or its refusal).
+- The host's envelope is relayed unchanged, success or failure: the same
+  document the local command answers, with no routing keys added. The
+  guarded retire apply is the routed `retire`, whose result carries
+  `server` and `target` as before.
+- A host that does not advertise the feature and API number is refused with
+  `E_REMOTE_INCOMPATIBLE`, naming both and the host's version, before
+  anything is sent. A name two homes share on the host is `E_AMBIGUOUS`.
+
 <a id="instance-git-state-oats-instance-gitdiff-instancegitapi-1-oats-0247"></a>
 ## Git and diff
 
@@ -1711,26 +1898,45 @@ accept `--server <id>`.
 {"context":"/w","level":"/w","file":"/w/oats-local.yaml","selected":null,
  "configurations":[{"name":"reviewers","harness":"claude","executable":null,"args":["--permission-mode","plan"],
                     "env":{"ANTHROPIC_API_KEY":{"fromEnv":"REVIEW_KEY"},"REVIEW_MODE":{"redacted":true}},
-                    "model":"opus","yolo":null,"source":"/w/oats-local.yaml","shadows":[]}]}
+                    "model":"opus","yolo":null,"default":false,"source":"/w/oats-local.yaml","shadows":[]}]}
 ```
 
 - **list**: `selected` is `null`, `{home, instance}` or `{soul, agentsRoot}`;
   `level` and `file` are `null` without an `oats-local.yaml` (the set is then
   empty). An environment literal is `{redacted: true}`, a reference
-  `{fromEnv}`; values never leave the file.
+  `{fromEnv}`; values never leave the file. `default` (0.32, feature
+  `launch-config-default`) is always a boolean: `true` marks this host's
+  default for the configuration's harness.
 - **set**/**remove**: `{name, action, level, file, before, after,
   effective}`. `set --file` takes `{harness, executable?, args?, env?, model?,
-  yolo?}` (`-` reads stdin). `--keep-env` keeps the declared environment when
-  `env` is omitted. Errors: `E_LOCAL_MISSING`, `E_BAD_ARGS` (including
-  `--home`/`--soul`), `E_LAUNCH_CONFIG_UNKNOWN`, `E_LAUNCH_CONFIG_INVALID`,
-  `E_CONFIG_BROKEN`, `E_HOME_UNKNOWN`.
+  yolo?, default?}` (`-` reads stdin); it replaces the whole entry and refuses
+  a key it does not know, so an editor sends `default` back to keep it.
+  `default: false` is written as its absence. A second `default: true` for a
+  harness is `E_LAUNCH_CONFIG_INVALID` with `details: {harness,
+  configurations: [<the declared one>, <this one>]}` and nothing is written;
+  moving the default is two writes, never an automatic move. `--keep-env`
+  keeps the declared environment when `env` is omitted. Routed with
+  `--server`, a definition with `default: true` to a host that does not
+  advertise `launch-config-default` is `E_REMOTE_INCOMPATIBLE` before
+  anything is sent (`default: false` is dropped). Errors: `E_LOCAL_MISSING`,
+  `E_BAD_ARGS` (including `--home`/`--soul`), `E_LAUNCH_CONFIG_UNKNOWN`,
+  `E_LAUNCH_CONFIG_INVALID`, `E_CONFIG_BROKEN`, `E_HOME_UNKNOWN`,
+  `E_REMOTE_INCOMPATIBLE`.
 - **preview** (read-only) answers `{context, selected, selection: {source,
   launchConfig, harness, model, yolo}, harness, model, modelSource, yolo,
-  launchConfig, launchConfigSource, executable: {path, declared,
-  resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
+  launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
+  declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
   true} | {name, reference: true}], command (redacted), prompt, hooks,
   preflight: [{check, ok, detail}], ok}`.
 
+`launchConfigDefault` (0.32) is `true` when `launchConfig` is this host's
+default for the harness rather than a chosen configuration; the spawn preview
+carries the same top-level field, `instance.json` records it as
+`launch.launchConfigDefault: true`, and `inspect --json` of a home answers
+`instance.launchConfig` and `instance.launchConfigDefault`. The closed `Launch`
+object is unchanged: its `effective.launchConfig` names the default
+configuration.
+
 A successful envelope can carry `ok: false`: show the failed `preflight`
 checks. The prompt is named, never the task body. A home predating launch
 recipes answers its frozen command with `selection.source: "frozen-command"`

package/docs/desktop-instance-start.md

@@ -67,4 +67,6 @@ before launch. Desktop does not scaffold a home or execute a launcher itself.
 Status collection reads each instance's recorded tmux socket and session,
 with one query per socket per collection. A launcher shell with a harness
 child remains running; a fallback shell or dead pane is stopped. Errors that
-prevent a reliable observation remain unknown. Herdr uses its saved target.
+prevent a reliable observation remain unknown. A row that records a Herdr
+target (Herdr was removed in 0.31.0) is never observed: it shows the kernel's
+`E_HERDR_REMOVED` text, and Open and Start are disabled.

package/docs/desktop.md

@@ -110,6 +110,42 @@ registered remote workspace the timer and definitions live on that server, so
 they do not depend on the Mac staying awake. See [Schedules](schedules.md) for
 the CLI, cron semantics, observed outcomes and recovery commands.
 
+## Instances on servers
+
+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
+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:
+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>`).
+
+## Remote terminals
+
+A terminal for an instance on a registered server is a viewer over ssh
+(`oats session attach --server`). When the link dies, ssh ends the viewer with
+exit 255 within about a minute, and the tab reconnects by itself. It keeps its
+place and scrollback, stops taking input, and shows "Disconnected from
+<server>" with a countdown and a **Reconnect now** button. Attempts wait 1, 2,
+4, 8 and 15 s, then 30 s each for as long as the tab is open. A successful
+attach resets that. Tmux redraws the screen when the viewer attaches again.
+
+Reconnecting stops, with a message and "Close this tab", when the server
+answers that the session is gone, the instance is unknown, the terminal limit
+is reached or the app's backend changed, and at once when ssh cannot be run on
+this computer. It stops after four attempts in a
+row in which OATS on this computer gave no answer, since that is more likely
+the local CLI failing than the link. It also stops when the viewer ends with
+any other exit code. Closing the tab ends the reconnecting. Reconnecting
+never stops or restarts the agent on the server: only the local ssh viewer
+ends.
+
 ## Attach files and screenshots
 
 Drop a file onto an agent terminal to insert its path into that agent's draft.