@awebai/oats 0.30.2 → 0.31.0

package/docs/desktop-cli-api.md

@@ -30,8 +30,9 @@ 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",
@@ -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
@@ -149,6 +154,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
@@ -1157,6 +1176,9 @@ it to a temporary copy (`soulFetched: true`).
   repeatable, `a.b=c` nests): a malformed pair is `E_BAD_ARGS`; a capability
   the soul does not resolve is `E_CAPABILITY_MISSING {capability, soul,
   modules}`.
+- Any other positional after the soul, or a flag spawn does not read, is
+  `E_BAD_ARGS` naming the argument, before anything is resolved; a bare
+  `key=value` is refused with the `--provider <capability> key=value` form.
 
 ### The decision
 
@@ -1204,8 +1226,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"}}}
@@ -1214,10 +1236,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).
 
@@ -1239,7 +1262,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 
 | Code | Details | When |
 |---|---|---|
-| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory or removed flags |
+| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul |
 | `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
 | `E_SOUL_UNKNOWN` | `{name, members, packages}` | no such soul, or not at `--agents-root` |
 | `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
@@ -1262,6 +1285,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 | `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
 | `E_SPAWN_INCOMPLETE` | `{instance, home, launched}` | |
 | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
+| `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
 | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
 | `E_SPAWN_FAILED` | | anything else |
 
@@ -1293,7 +1317,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`.
@@ -1350,8 +1374,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,
@@ -1375,6 +1404,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
 
@@ -1670,8 +1775,9 @@ selection flags. See [the start workflow](desktop-instance-start.md).
 - A lost response does not mean the launch failed: check status before a
   retry. A remote home's saved route names its execution host.
 - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
-  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*`,
-  `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`.
+  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*` (among them
+  `E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
+  started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`.
 
 ### Upload
 

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,26 @@ 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.
 
+## 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.

package/docs/execution-targets.md

@@ -35,33 +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,
-  with no negotiation. New sessions use protocol 20. A recorded session target
-  may carry protocol 20 or 22, and each call checks that the server's snapshot
-  reports the recorded protocol.
+### 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
 
@@ -77,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
@@ -112,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

@@ -54,7 +54,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 |
 

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

@@ -64,6 +64,14 @@
         }
       }
     },
+    "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/release-notes/v0.30.3.md

@@ -0,0 +1,75 @@
+# OATS 0.30.3
+
+## Changed
+
+- **Desktop: the whole app works from the keyboard, with a Linux-sane keymap.**
+  Changed Linux and Windows defaults: the command palette is now Ctrl+Shift+P
+  on Linux and Windows; close tab Ctrl+Shift+W; split Ctrl+Shift+E /
+  Ctrl+Shift+O (close the split Ctrl+Shift+Alt+W); Spawn instance
+  Ctrl+Shift+N; the theme cycle has no default chord (on macOS too; the palette
+  keeps it). No default chord takes a key a program in the terminal reads:
+  plain Ctrl+W, Ctrl+K, Ctrl+\, Ctrl+P and Ctrl+B, F6, Alt+digit and
+  Ctrl+PgUp/PgDn (and ⌃digits on macOS) always reach the program, and nothing
+  binds Super. New: go to tab (⌥⌘1–⌥⌘9 / Alt+1–Alt+9), Ctrl+PgDn / Ctrl+PgUp,
+  ⌘3 / Ctrl+3 for Automations, and F6 / Shift+F6 to move between the sidebar,
+  the instances, the main area and the instance panel; from a terminal,
+  ⇧⌘F6 / Ctrl+Shift+F6 leaves it for the next region. Your own rebinds are
+  kept; one that now clashes with another shortcut is flagged in the shortcuts
+  editor, never changed for you. Quick Open (⌘P / Ctrl+P)
+  now opens the spawn dialog for the soul you pick, and Esc takes you back to
+  where you were; ⌘↵ / Ctrl+Enter spawns from any field, and Tab walks the
+  form in the order you see it. Keyboard gaps found in an audit are closed:
+  roster rows of unknown state, Independent nodes in the Active overview, the
+  Automations row menu, the schedule form and focus lost after switching tabs
+  or views. The keymap and the audit are in
+  `packages/desktop/docs/desktop-keyboard.md`.
+- **Desktop: the spawn dialog says why each capability is there.** In "What
+  will be created", each Capabilities row shows a muted reason tag beside its
+  source: **Soul**, **Workspace default**, or, for a workspace default that
+  fills a core slot, **Workspace default · messaging** (knowledge, messaging or
+  tasks). It is the preview's `composedFrom`, read only from a CLI that reports
+  `preview-composed-from`; with an older CLI the rows show no tag, never a
+  guess. The Core capabilities table is unchanged.
+- **Desktop: clearer overview lines, a centred rail, pinned Workspace controls.**
+  The Active overview draws parent links as smooth curves from a parent's
+  bottom to its child's top, with dashed arcs between siblings, in a colour
+  that is visible in every theme. The collapsed instance panel's icons sit
+  on its centre line. In Workspace, the Capabilities section pills and search
+  and the Teams header stay in view while the content scrolls, and scrolling
+  to the end of a list no longer moves the whole window.
+
+## Fixes
+
+- **Plain `oats` inside an instance is the kernel that launched it.** On a
+  machine with two kernels side by side (a global 0.24 for classic
+  deployments and a 0.30 prefix install), an agent typing `oats` got whatever
+  `PATH` found first: `oats aweb teams` answered `E_UNKNOWN_COMMAND` in a 0.30
+  home. Every launch (spawn, `session start`, `session restart`) now writes
+  `<home>/.oats/bin/oats`, a link to the launching kernel, and runs the harness
+  with `<home>/.oats/bin` first on `PATH`. A restart by another kernel
+  re-points it. The recipe records the target as `launch.kernelBin`, and
+  `oats status` shows it (`kernel:`) when it is not the running `oats`. A
+  launch that cannot write the link fails with `E_LAUNCH_SHIM`. Existing homes
+  get the link at their next start or restart.
+- **`oats spawn` refuses an argument it does not read.** A positional after
+  the soul, or a flag spawn does not know, is `E_BAD_ARGS` naming it, before
+  anything is resolved or created. `oats spawn <soul> join=oats` used to be
+  accepted and the bare `join=oats` ignored, so the instance joined nothing;
+  the refusal now names the form that was meant, `--provider <capability>
+  key=value`. A routed spawn (`--server`) is refused on this machine, before
+  the server is contacted.
+- **Herdr 0.9 spawns work.** A new Herdr session was always opened at protocol
+  20, so `oats spawn --backend herdr` against Herdr 0.9, which speaks protocol
+  22, failed with "Herdr snapshot does not match selected protocol 20". A new
+  session now records the protocol its server reports when it is one OATS
+  supports (20 or 22), and refuses any other by name. A recorded session is
+  still checked against its recorded protocol on every call and is never
+  renegotiated. The Desktop attaches to protocol-22 sessions too; it accepted
+  only protocol 20 before. An instance recorded at protocol 20 is unreachable
+  after an in-place Herdr 0.8 → 0.9 upgrade until it is respawned.
+- **A Herdr launch no longer arrives cut.** OATS typed the launch command into
+  the new pane before its shell had started. The terminal's line buffer
+  (1024 bytes on macOS) dropped the rest of the longer command, so the harness
+  never started: the shell waited on an unclosed quote. On Herdr 0.9, 0 of 5
+  fresh panes ran a 2000-character command intact. A launch now waits, up to
+  10 s, until the pane has drawn its prompt, then types; 5 of 5 ran intact.