@awebai/oats 0.30.3 → 0.32.0

package/docs/execution-targets.md

@@ -35,39 +35,56 @@ variables point at are described in
 
 ## Backends
 
-`oats spawn --backend tmux|herdr` chooses the backend (default `tmux`). The
-backend binary must be installed on the execution host. The chosen session
-target is recorded twice: in `instance.json` and in an independent lifecycle
-receipt. Every session command checks that the two agree
-(`E_RUNTIME_AUTHORITY_MISMATCH` otherwise).
+tmux is the only session backend. `oats spawn --backend tmux` is accepted (it
+is the default); `tmux` must be installed on the execution host. A launched
+home keeps the session it recorded: `session start` and `restart` never
+re-read the defaults. The session target is recorded twice: in
+`instance.json` and in an independent lifecycle receipt. Every session command
+checks that the two agree (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise).
 
 ### tmux
 
-Each instance is a window named after the instance in the tmux session
-`pi-agents` (override with `PI_AGENTS_TMUX_SESSION`). The receipt records the
+Each instance is a window named after the instance in a tmux session: the
+deployment's `session.tmuxSession`, else `OATS_TMUX_SESSION`, else
+`PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. Before
+0.31 the default was `pi-agents`; a home launched then keeps the `pi-agents`
+session it recorded, and `oats status` reads each home on its recorded tmux
+socket and session, never the caller's `$TMUX` server: a caller outside the
+agents' tmux (ssh, cron, a plain terminal) sees the same liveness as `session
+inspect`. A recorded server that cannot be read gives `running: null` with
+`runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
+inspect --json` reports the session a new spawn would open in as `session`
+(`{tmuxSession}`). A spawn refuses an instance name that is a live window in the
+session it would open in (`E_INSTANCE_NAME_TAKEN`); a live window of that name
+in another session, such as a `pi-agents` window after the default moved, does
+not block it. Session commands target each home's exact recorded window, so
+the two never mix. The receipt records the
 session, window and socket. The spawn result prints the attach command.
 
-### Herdr
-
-Each instance is a Herdr workspace with one pane. The receipt records the
-binary, socket, workspace id, pane id, terminal id and protocol. The terminal
-id distinguishes a replacement occupant of the same pane.
-
-- `--herdr-socket <path>` uses an operator-managed Herdr server. OATS never
-  starts a different server when that socket cannot be inspected.
-- Without it, OATS uses `$XDG_CONFIG_HOME/herdr/sessions/oats/herdr.sock`
-  (default `~/.config/...`) and starts `herdr --session oats server` if no
-  server is running there.
-- The adapter speaks the Herdr socket API at an explicit protocol version,
-  20 or 22. A new session records the protocol its server reports (20 for
-  Herdr 0.8, 22 for 0.9) and refuses any other; before 0.30.3 it always
-  selected 20, so Herdr 0.9 could not be spawned on. A recorded target is
-  never renegotiated: each call, the kernel's and the Desktop's, checks that
-  the server's snapshot reports the recorded protocol.
-- Herdr cannot give a pane a command at creation, so OATS types the launch
-  command into the pane's shell. It waits until the shell has drawn its prompt
-  (`herdr pane read`, at most 10 s): text typed earlier is cut at the
-  terminal's line-buffer limit.
+### Herdr (removed in 0.31.0)
+
+OATS no longer supports Herdr. Everything that meets it refuses with
+`E_HERDR_REMOVED`, whose message starts `Herdr is no longer supported by OATS
+(removed in 0.31.0); tmux is the only session backend.` and says what to do:
+
+- `oats spawn --backend herdr` or `--herdr-socket`, local or routed with
+  `--server` (refused before the server is contacted), and `oats server add
+  --herdr`: remove the flag, or use tmux.
+- A schedule's `backend: herdr` or a trigger's `spawn.backend: herdr`: the
+  message names the file and key; remove it, or use tmux. A stored local job
+  that names it is reported invalid and never runs.
+- `session inspect`, `attach`, `input`, `start`, `restart` and `instance stop`
+  on a home a Herdr-era kernel recorded (its `instance.json` records a
+  `sessionTarget` or `backend: "herdr"`, or its receipt records a session
+  target): retire it and spawn a new instance, which opens in tmux.
+- `oats retire` of such a home needs no Herdr: when no process works in the
+  home it proceeds as for an absent session; when one does, it refuses and
+  names the pids, so stop its Herdr pane first (for example `herdr --session
+  oats server stop`).
+
+`oats status` lists such a home with `running: null`, `runtimeState:
+"unsupported"` and the refusal as `runtimeError`. A server registration or
+saved route that records `herdrPath` still loads; the field is ignored.
 
 ## Lifecycle
 
@@ -83,8 +100,8 @@ id distinguishes a replacement occupant of the same pane.
 
 `session start` keeps the instance's identity, work tree and notes. It runs no
 spawn hooks and creates no new home. It runs the recorded launch recipe on the
-recorded tmux session or Herdr server; a `--no-launch` home starts on the
-default tmux server.
+recorded tmux session; a `--no-launch` home starts on the default tmux
+server.
 
 - `--model`, `--launch-config <name>|none`, `--harness` and `--yolo` /
   `--no-yolo` re-resolve the recipe against the home's recorded context and
@@ -118,18 +135,18 @@ oats session input --home /abs/home --text-file message.txt --json
 oats session attach --home /abs/home
 ```
 
-- **inspect** reports `backend`, `present` and `state`: the Herdr agent state
-  when available, `unknown` for a live harness, `shell` for a fallback shell,
+- **inspect** reports `backend`, `present` and `state`: `unknown` for a live
+  harness, `shell` for a fallback shell,
   `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
   backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
 - **input** submits UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
-  NUL) followed by Enter: bracketed paste in tmux, `pane run` in Herdr. The
-  text is never run by a shell. A fallback shell, a stopped session or a split
+  NUL) followed by Enter, as a bracketed paste. The text is never run by a
+  shell. A fallback shell, a stopped session or a split
   tmux window is refused. `submitted: true` means the terminal accepted the
   text, not that the agent processed it. Wake schedules and messaging
   capabilities use this command ([schedules.md](schedules.md)).
-- **attach** is interactive and takes no `--json`. It opens a Herdr terminal
-  viewer, or a temporary tmux session linked to the agent's window alone.
+- **attach** is interactive and takes no `--json`. It opens a temporary tmux
+  session linked to the agent's window alone.
   Closing the viewer leaves the agent running.
 
 ### Attachments

package/docs/implementation.md

@@ -44,6 +44,7 @@ published to npm. Its developer docs are in
 | module | owns |
 |---|---|
 | `remote.mjs` | repo refs, reading Git remotes, content digests |
+| `local-inputs.mjs` | the local configuration a command read, for `observation.localRevision` |
 | `workspace.mjs` | workspace, membership and soul files; discovery |
 | `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
 | `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
@@ -54,7 +55,7 @@ published to npm. Its developer docs are in
 | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
 | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
 | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
-| `herdr.mjs`, `tmux-config.mjs`, `session-*.mjs` | session backends and terminal input |
+| `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
 | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation, the hook environment rules, the readiness wire |
 | `servers.mjs` | routing commands to a registered server |
 
@@ -62,6 +63,63 @@ The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
 a provider. Provider behaviour lives in capabilities; the kernel supplies
 their contracts ([layers](layers.md)).
 
+### The remote read path
+
+Every CLI command owns one read session (`createReadSession` in
+`remote.mjs`, carried to every remote call as `remoteOptions.session`; the
+CLI closes it when the command ends). A library caller without a session
+gets the plain per-call behaviour. Within a session:
+
+- a head is observed once per (cache repo, ref), and a commit peeled once; at
+  most eight observations run at once (`OBSERVE_LIMIT`), each holding its slot
+  for all its git work (the `ls-remote` and the fetch of the commit it names,
+  or the fetch of a reused record's commit);
+- a whole-workspace discovery prefetches its members' heads together with the
+  host's (`prefetchMembers` in `workspace.mjs`): the member list comes from the
+  host's last observation record and the parsed `workspace` entry at that
+  commit, never from a git process, and the answer still uses the list at the
+  host commit observed now. A prefetched failure is adopted by the member's own
+  observation, not retried in the command. A prefetch no caller adopts (the
+  host could not be observed, or the member was dropped since) is abandoned:
+  one still queued runs no git. `observeWorkspace` alone (the `teams` reads,
+  `inspect --home`) never prefetches;
+- closing the session (the end of the command, or `process.exit`) rejects
+  every queued observation and aborts every git child still running for it
+  (the session's `AbortSignal` rides every `runGit`). `runGit` starts git as
+  its own process group, so a timeout, an output overflow or an abort kills
+  git's ssh or remote helper with it; before a capability
+  command runs its provider, the CLI ends the idle batch readers
+  (`closeBatches`);
+- a commit's tree is listed once (`git ls-tree -r -t -l`, bounded by
+  `TREE_INDEX_BUDGET`; anything odd falls back to the per-path reads), and
+  blobs come from one `git cat-file --batch` reader per cache repo (at most
+  12 open, killed through `process-group.mjs` on timeout and at close);
+- discovery reads members eight at a time (`DISCOVERY_CONCURRENCY`) with
+  serial results: declaration order, the first failure in that order. The
+  observations and the member reads are two pools, so a discovery runs at
+  most sixteen short-lived git processes at once (eight of them fetches at
+  most), plus up to twelve cat-file readers: twenty-eight git processes. One
+  shared pool would deadlock: a member read holding a slot waits on its
+  member's observation, which needs a slot of its own.
+
+Across commands, `memoAtCommit` keeps parsed reads under
+`<cache>/.parsed/<kernel fingerprint>/`, keyed by (repo key, full commit,
+item). The items: `workspace` (the workspace file), `membership` (a member's
+backlink outcome), `enumerate` (a member's souls and capabilities),
+`package-soul` and `external-soul` (one soul file each; their error handling
+differs), `package-manifests` (a package's manifests), `list` (a skill
+listing) and `tree-oids` (the tree ids of a set of directories). An entry is only ever a pure function of those bytes and this kernel's
+code, never local state and never a transient error; it is written
+atomically, a corrupt one is a miss, and `pruneStores` bounds the store
+(`PARSED_LIMITS`, least recently used first). `--max-age` adds the observation
+store `<cache>/.observed/` ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)):
+one record per (repo key, ref args, url digest), so two spellings of one repo
+keep a record each; the url itself is never written. Adding a cached item
+means choosing an item name unique to its producer (the item string its
+call site passes to `memoAtCommit`, or to `atCommit` in `workspace.mjs`) and
+adding it to `test/parsed-cache.test.mjs`; `test/read-path-scale.test.mjs` pins the member
+scaling by call count.
+
 ## Tests and gates
 
 | command | what it checks |

package/docs/integrations.md

@@ -41,7 +41,7 @@ arrives from.
 # oats-workspace.yaml: one default per slot, for every soul
 packages:
   oats.okf: v4.0.5
-  oats.aweb: v1.17.1
+  oats.aweb: v1.17.3
   oats.linear: v1.0.1
   oats.jira: v1.0.1
 defaults:

package/docs/oats-local.schema.json

@@ -60,10 +60,19 @@
             "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops."
           },
           "model": { "type": "string", "minLength": 1, "description": "Model for this configuration's harness; overrides the soul default when this configuration is selected." },
-          "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." }
+          "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." },
+          "default": { "type": "boolean", "description": "This host's baseline for its harness (0.32, feature launch-config-default): a new launch that picks this harness without naming a configuration (a soul's or souls.launch preference, --harness, the host default) runs this configuration's executable, args, env and yolo; its model is the last fallback. At most one per harness. `--launch-config none` bypasses it. OATS 0.31 and older refuse the key." }
         }
       }
     },
+    "session": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "This host's terminal session defaults for NEW launches (0.31). A launched home keeps the session it recorded.",
+      "properties": {
+        "tmuxSession": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "The tmux session new tmux instances open their windows in. Absent: OATS_TMUX_SESSION, else PI_AGENTS_TMUX_SESSION (pre-0.31), else oats-agents." }
+      }
+    },
     "host": {
       "type": "object",
       "additionalProperties": false,

package/docs/official-catalog.md

@@ -11,7 +11,7 @@ or workspace membership alone does not make a package official.
 |---|---|---|---|
 | `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
-| `oats.aweb` | `v1.17.1` | `oats.aweb` (messaging) | |
+| `oats.aweb` | `v1.17.3` | `oats.aweb` (messaging) | |
 | `oats.engineering` | `v1.3.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |

package/docs/packages.md

@@ -76,7 +76,7 @@ members:
 packages:
   oats.framework: v1.4.1
   oats.okf: v4.0.5
-  oats.aweb: v1.17.1
+  oats.aweb: v1.17.3
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
 ## `oats package add | remove`
 
 ```bash
-oats package add oats.aweb v1.17.1                         # a catalog version
+oats package add oats.aweb v1.17.3                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```

package/docs/plans/0.30-close-out.md

@@ -69,8 +69,11 @@ Found by the rehearsals, and fixed before the tag:
 ## After the tag
 - **Flag day:** the oats.engineering release with the souls' `launch:` (experts on Claude Code +
   Opus 5.5; `code-reviewer` on Codex + Astra; compat `>=0.30.0`), and committing the shared team id.
-- **0.30.1:**
-  - the kernel items that miss the tag: retire of homes whose session is gone, automations.trust;
+- **0.30.1:** one release, cut when the Desktop load work has merged (the kernel read-path PR with
+  `observe-max-age` and `observation.localRevision`, Desktop #321 and #322), or on 2026-09-30 18:00 UTC,
+  whichever comes first; what has not merged by then goes to 0.30.2. Retire of homes whose session is
+  gone (#299) and automations.trust (#300) shipped in 0.30.0. The kernel items below have no owner yet:
+  each rides 0.30.1 only if it merges before the cut.
   - deployment-scope capability commands without `--soul`;
   - the case-8 pre-check (`E_TEAM_UNCONFIGURED`).
   - the kernel refuses an unrecognised spawn argument (a bare `join=oats` without
@@ -79,5 +82,5 @@ Found by the rehearsals, and fixed before the tag:
     FIRST on the instance's PATH and records it in the launch recipe, so plain `oats` inside an
     instance is the kernel that made it (two kernels side by side: a 0.30 home ran the global 0.24.6
     and `oats aweb` was `E_UNKNOWN_COMMAND`; the injected instructions tell agents to run plain `oats`).
-- **Parked:** item L (`git rm agents/`, cli-dev-v2-native). It needs the GitHub `workflow` token
-  scope from the human on the lead's machine.
+- **Done:** item L merged in #314 (d4f68da9): the remaining legacy `agents/` soul trees and the
+  `validate:okf` gate are removed.

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

@@ -0,0 +1,130 @@
+# OATS 0.31.0
+
+## Changed
+
+- **New tmux instances open in the tmux session `oats-agents`, not
+  `pi-agents`.** Running instances are unaffected: a home launched before 0.31
+  keeps the `pi-agents` session it recorded, `session start` and `restart` put
+  it back there, a self-retire kills its recorded window, and `oats status` and
+  the Desktop read each home in its recorded session. To keep new instances in
+  `pi-agents`, add one line to the deployment's `oats-local.yaml`:
+
+  ```yaml
+  session: { tmuxSession: pi-agents }
+  ```
+
+  `OATS_TMUX_SESSION` also sets it, and `PI_AGENTS_TMUX_SESSION` is still
+  honoured, read when the spawn runs. `oats inspect --json` reports the session
+  a new spawn would open in as `session`.
+- **Routed ssh calls share one connection per host and notice a dead link.**
+  Every `--server` call, `server roster` and `session attach --server` runs
+  ssh with `ControlMaster=auto`, `ControlPath=~/.oats/ssh/%C` and
+  `ControlPersist=60`, plus `ServerAliveInterval=15` and
+  `ServerAliveCountMax=3`. The probe, the command and an attached viewer
+  ride one authenticated connection. A viewer whose link dies ends within
+  about 60 s with a message naming the command to reattach, instead of
+  hanging. These options override any `Control*` settings for the host in
+  `~/.ssh/config`. When the control socket path would not fit the 104-byte
+  limit or has characters ssh reads as syntax, or `~/.oats/ssh` is not
+  private to you, calls run with connection sharing off
+  (`ControlPath=none`) and the command warns once per server
+  ([servers.md](../servers.md#connections)).
+- **The version probe is asked once per process** per server and target.
+- A server too old for `oats session` is refused with the tmux command for
+  the instance's recorded session and window, not a fixed `oats` session.
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.32.0`** (was `<0.31.0`), so
+  it runs against this release's kernel.
+- **oats.aweb 1.17.3** (catalog and workspace pin, and the bundled mirror).
+  Session-delivery guidance matches aw 1.36.15's host wake broker: it
+  presents either a line naming what is waiting or the full mail/chat event,
+  and recovery after an uncertain crash, compaction or restart goes by exact
+  message id (`aw mail show --message-id <id> --json`) or paged
+  `aw mail inbox --show-all --json` with `--cursor`. A resident grant's
+  `renew: launch` re-registers the wake broker with the new grant, and grant
+  seats start with `aw whoami`.
+
+## Added
+
+- **Any instance on a server is controllable from here, whoever spawned it.**
+  `retire --server` and the routed `session` commands (inspect, attach,
+  start, restart, upload), `inspect`, `operation` and `launch-config` reach
+  an instance with no saved route by `--home`, or by a name the server's
+  roster lists once. A name two homes share there is refused with
+  `E_AMBIGUOUS`, listing the homes. Roster rows gain `addressable`, and
+  `savedRoute` is information only ([servers.md](../servers.md#run-there)).
+- **The Desktop's reads and lifecycle plans route to the instance's
+  machine.** `readiness`, `instance events`, `instance git`, `instance diff`,
+  `instance stop --plan|--apply` and `retire --plan` (and its guarded apply)
+  take `--server <id>`; the host's kernel does the work, Git included, and
+  its envelope is relayed unchanged. A host that does not advertise the
+  feature is refused with `E_REMOTE_INCOMPATIBLE` before anything is sent.
+  `version --json` lists them in `remote`: `readiness`, `instance-events`,
+  `instance-git`, `lifecycle-plans`
+  ([desktop-cli-api.md](../desktop-cli-api.md#routed-reads-and-plans)).
+- **Remote roster rows carry the host's facts.** `oats server roster --json`
+  instance rows relay `identity`, `identityAddress`, `teams`, `startedAt`,
+  `createdAt`, `model`, `runtimeState`, `parentInstance`, `siblingInstance`,
+  `relation`, `relativeTo` and `spawnOrigin` from the host's `status --json`,
+  `null` where the host does not supply them
+  ([desktop-cli-api.md](../desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
+- **A remote terminal in the Desktop reconnects after a lost link.** A
+  viewer that ssh ends with exit 255 keeps its tab and scrollback, goes
+  inert, and re-attaches with backoff (1, 2, 4, 8, 15 s, then every 30 s),
+  with **Reconnect now** to try at once. It stops with the reason when the
+  server says the session is gone or refuses the attach, at once when ssh
+  cannot be run on this computer, or after four
+  attempts in a row in which this computer's `oats` gave no answer
+  ([desktop.md](../desktop.md#remote-terminals)). Reconnecting never touches
+  the agent on the server.
+
+## Fixed
+
+- **`oats status` reads liveness from each instance's recorded tmux socket**,
+  not the caller's `$TMUX` server. Outside the agents' tmux (every `status
+  --server` over ssh, cron, a plain terminal) running instances read
+  `running: false`, and a row on the default server could read `true`. Now
+  `running` agrees with `session inspect`; a recorded server that cannot be
+  read gives `running: null` with `runtimeState: "unreachable"` (#347).
+- **`session attach --server` exits 255 when ssh fails before the viewer
+  opens** (the version probe, or resolving a name through the host's roster),
+  as it does when ssh fails under the viewer; it exited 1, so a caller that
+  reconnects on 255 gave up on a flapping link. Every other refusal still
+  exits 1. An ssh failure now names the host: `ssh to <host> failed: …`
+  (#349).
+- **An `E_SSH` envelope says when ssh never started.** A routed `--json`
+  command whose ssh could not be run on this machine (not installed, not
+  executable) answers `E_SSH` with `error.details: {"sshStarted": false}`, so
+  a caller can stop retrying; a failed link carries no details, as before.
+
+## Removed
+
+- **Herdr.** tmux is the only session backend; cross-machine work goes over
+  ssh routing (`--server`), which never used Herdr. Nothing is migrated
+  silently: everything that meets Herdr refuses with `E_HERDR_REMOVED`, whose
+  message says what to do.
+  - `oats spawn --backend herdr` or `--herdr-socket` (local, or routed with
+    `--server`, refused before the server is contacted) and `oats server add
+    --herdr`: remove the flag, or use tmux. `--backend tmux` is still accepted,
+    and `oats version --json` advertises `sessionBackends: ["tmux"]`.
+  - A schedule's `backend: herdr` or a trigger's `spawn.backend: herdr`: the
+    message names the file and key; remove it, or use tmux. A stored local job
+    that names it is reported invalid and never runs.
+  - `session inspect`, `attach`, `input`, `start`, `restart` and `instance
+    stop` on an instance opened in Herdr: retire it (`oats retire <name>`) and
+    spawn a new instance; it opens in tmux. `oats status` lists such an
+    instance with `running: null`, `runtimeState: "unsupported"` and the
+    refusal as `runtimeError`, and never fails because of it.
+  - `oats retire` of an instance opened in Herdr works without Herdr. When a
+    process still works in its home it refuses, naming the pids: stop its
+    Herdr pane (for example `herdr --session oats server stop`), then retire.
+  - A server registration or saved route that records `herdrPath` still
+    loads; the field is ignored.
+  - **The Desktop** no longer offers Herdr as a session backend and never
+    opens a Herdr terminal; it refuses one with `E_HERDR_REMOVED`, including
+    for a remote host still on an older OATS. An instance opened in Herdr
+    stays in the roster with the reason; its Open, Start and Restart are
+    disabled, and Remove (retire) still works, so it can be retired and
+    spawned again in tmux.
+
+  An idle Herdr server that OATS started (session `oats`) is not OATS state;
+  stop it with `herdr --session oats server stop`.

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

@@ -0,0 +1,137 @@
+# OATS 0.32.0
+
+## Added
+
+- **A default launch configuration per harness.** `default: true` on a
+  launch configuration in `oats-local.yaml` makes it this machine's baseline
+  for its harness. Every new launch of that harness that names no
+  configuration runs its executable, args, env and `yolo`: a soul's own
+  `launch:`, an inline `souls.launch` preference, `--harness`, the host
+  default. For example, every claude instance on a machine runs with its
+  `CLAUDE_CONFIG_DIR`:
+
+  ```yaml
+  launch-configs:
+    mine:
+      harness: claude
+      default: true
+      env: { CLAUDE_CONFIG_DIR: /home/me/.claude-personal }
+  ```
+
+  The model still comes from whatever chose the harness; the default's
+  `model` is only the last fallback. A named configuration runs as declared,
+  and `--launch-config none` asks for the bare harness. One default per
+  harness (a second is refused, naming both). `oats launch-config list`,
+  `spawn --preview`, `launch-config preview`, `instance.json` and
+  `oats inspect --home` say when a launch came from the default
+  (`launchConfigDefault`), yolo included. Existing instances keep their
+  launch until `--reselect-launch` or a respawn, and meanwhile show the
+  `launch-changed` readiness warning. Feature
+  `launch-config-default`
+  ([configuration.md](../configuration.md#the-harness-default)).
+  **Declaring a default needs OATS 0.32+ for every kernel that reads this
+  deployment:** OATS 0.31 and older refuse the whole `oats-local.yaml`
+  (`E_WORKSPACE_SCHEMA`). A routed `launch-config set --server` with
+  `default: true` to an older host is refused (`E_REMOTE_INCOMPATIBLE`)
+  before anything is sent.
+
+- **Every instance a server reports is first-class in the Desktop, whoever
+  spawned it.** A remote row opens its terminal, starts, restarts, stops and
+  retires, and shows its readiness, activity, Git and diffs, just like a local
+  one; only its pull request is not read here, since the forge reads this
+  computer's clones. Stop and Remove keep their confirmations: the plan and
+  its guarded apply run on the instance's machine. Every command goes to the
+  server by the instance's home (`--server <id> --home <path>`), never by a
+  bare name, so two instances with the same name stay apart. While a read is
+  in flight, the view says "Reading from <server>…". When the server refuses,
+  it shows the server's code and message under a headline that usually names
+  the server; it never falls back to a local read. A remote stop or remove
+  that loses its link reads as an unknown outcome, never a failure, and the
+  server's roster is read again at once
+  ([desktop.md](../desktop.md#instances-on-servers)).
+- **A row that can't be opened says why, on the row.** The roster shows a short
+  reason where it said "state unknown": Herdr no longer supported, gone from
+  <server>, not reachable on <server>, or <server> not reached. The full
+  sentence stays in the row's tooltip and its actions menu. For an instance a
+  server no longer lists, it names the command that removes it from this
+  computer (`oats server forget <server> --instance <name>`).
+- **This computer's OATS 0.31 decides which server rows can be used.** The
+  Desktop accepts OATS CLIs up to 0.32.x. With a local OATS before 0.31, which
+  does not report that fact, an instance spawned from this computer stays
+  usable through its saved route, as before; its routed reads and plans ask you
+  to update OATS here.
+- **A team card lists its members wherever they run.** On a local workspace's
+  Teams page, each team with a provider id lists every instance in it: this
+  workspace's, and every registered server's whose messaging identity is in
+  that team. They are grouped by machine ("This computer" first), with each
+  one's state in words. A member's name shows its roster row, where every
+  action lives; **Terminal** opens a running member there. A server whose
+  last roster read failed keeps its last-known members under "<server> · not
+  reached"; servers with nothing to show are named under the page head. The
+  card's count reads "N members · M on other machines". The Desktop reads
+  this from what it already holds and runs nothing new
+  ([desktop-teams.md](../../packages/desktop/docs/desktop-teams.md#team-members)).
+- **The spawn dialog asks "Where to run" up front** (it was "Run on", under
+  Developer settings). "This computer" comes first, then each registered
+  server. A server is disabled, with the reason, when it wasn't reached or
+  the roster knows only an older registration of it. With a server chosen,
+  the dialog says where the instance will run, and the relationship picker
+  lists only that server's instances: a relation never crosses machines. When
+  the server refuses the spawn (a soul it doesn't offer, for example), the
+  dialog says so in the server's own words.
+- **The Desktop keeps and sets a harness's default launch configuration.**
+  Editing a configuration marked `default: true` saves it with its default
+  intact, and with an OATS that has `launch-config-default` the editor offers
+  "Default for <harness> on this machine" for this computer's own
+  configurations. A remote host's default survives editing too, but is set on
+  that host. A second default for the same harness is refused in OATS's own
+  words; unset the old one first.
+
+- **Faster read verbs, and `--max-age <s>` to reuse recent remote heads**
+  (feature `observe-max-age`). `status`, `workspace status`, `souls`,
+  `capabilities` and `inspect` start far fewer git processes, cache what
+  they parse by commit, and start the members' remote reads together with the
+  host's. With `--max-age` they reuse a head observed in the last `<s>`
+  seconds and report `observation {observedAt, reused, localRevision}`
+  (`localRevision` changes whenever the local configuration read for the
+  answer does). See
+  [Observation reuse](../desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311).
+
+## Fixed
+
+- **A remote spawn with an empty opening instruction starts it waiting**, as
+  the dialog says. It was refused ("--task needs a value").
+- **Focus stays put on the Workspace's Teams, Capabilities and Setup pages.**
+  Every roster poll rebuilt the page, since the workspace status it compared
+  carries a fresh observation time each time, so keyboard focus (and the
+  caret in the add-team form) fell back to the page every few seconds.
+- **A click on a Desktop instance's actions menu does what it says.** With the
+  pointer over the open menu, the row no longer counted as hovered, so its
+  tools, the menu included, went hidden and a click on an item did nothing;
+  the keyboard still worked.
+- **The Stop and Remove confirmations show only their own choices.** Stop
+  showed Remove's "delete the worktree" and "delete the local branch" options
+  (enabled, and ignored), and Remove showed Stop's "include recorded children".
+
+- **A remote read that times out no longer leaves its ssh or https helper
+  running.** The kernel killed git but not the ssh or `git-remote-https` it
+  had started, which stayed connected to an unreachable host until its own
+  connection gave up. Git now runs as its own process group, and a timeout
+  (or the end of the command) kills the whole group.
+
+- **A capability command whose provider dies of a signal exits as the shell
+  reports it** (128 + the signal number, 130 for a Ctrl-C), not 1.
+
+- **`oats --help` piped into another program is no longer cut off at 8 KB.**
+  The top-level usage (about 20 KB) now arrives whole, including the
+  "Observation reuse" section; exit codes are unchanged.
+
+## Removed
+
+- **`oats-claude-config` is no longer read.** The one-line file that named
+  the claude binary for every deployment below it is replaced by the claude
+  default launch configuration. A new claude launch with one in reach is
+  refused with `E_CLAUDE_CONFIG_REMOVED`, naming the file and the
+  configuration to declare instead (`harness: claude`, `executable: <the
+  name it held>`, `default: true`); then delete the file. Instances already
+  launched with it keep their recorded executable.

package/docs/schedules.md

@@ -54,7 +54,10 @@ both are evaluated by the croner library.
   launchConfig?, harness?, model?, yolo?, wake?}` — every due minute launches
   one disposable instance of `agent` with the options `oats spawn` takes.
   `agentsRoot`, when given, must be the deployment's `agents/` root; `repo`
-  is the work repository, as `--repo`. `model` is a model id (a letter or
+  is the work repository, as `--repo`. `backend` is `tmux`; `backend: herdr`
+  is refused (`E_HERDR_REMOVED`, naming the file and key: Herdr was removed in
+  0.31.0), and a stored job that names it is reported invalid and never runs.
+  `model` is a model id (a letter or
   digit, then letters, digits and `. _ : / @ + - [ ]`, at most 128
   characters) or `@native-default`; `agent` and `repo` never start with `-`,
   so no value can be read as an option of the child `oats spawn`. Each run is