@awebai/oats 0.30.2 → 0.31.0

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/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

package/docs/servers.md

@@ -26,13 +26,59 @@ oats server remove build
 - `--path` prepends directories to the minimal remote PATH of every routed
   command (`~/.local/bin:/opt/pi/bin`), where the remote spawn looks for the
   harness binary.
-- `--herdr` records the remote Herdr path in the registration and in each
-  saved route. Routed commands do not pass it on; the remote kernel finds
-  `herdr` on its own PATH.
+- `--herdr` is refused (`E_HERDR_REMOVED`): Herdr was removed in 0.31.0. A
+  registration or saved route that still records `herdrPath` loads; the field
+  is ignored, never written or printed.
 - `--label` sets a display name. `--replace` overwrites an existing id.
 - Registrations live in `~/.oats/servers.json` on this machine, never in a
   repository.
 
+## Connections
+
+Every routed ssh call carries these options, before `--` and the host:
+
+| Option | Why |
+|---|---|
+| `BatchMode=yes`, `ConnectTimeout=15` | a prompt or an unreachable host fails fast |
+| `ServerAliveInterval=15`, `ServerAliveCountMax=3` | a link that died without a reset ends the call, an attached viewer included, within about 60 s |
+| `ControlMaster=auto`, `ControlPath=~/.oats/ssh/%C`, `ControlPersist=60` | every call to one host (the probe, the command, a viewer, concurrent Desktop reads) shares one authenticated connection, kept 60 s after its last client |
+
+- Options given with `-o` override `~/.ssh/config`, so these replace any
+  `ControlMaster`, `ControlPath` or `ControlPersist` set there for the host.
+  Everything else in your ssh config (users, keys, `ProxyJump`, host
+  verification) applies as usual; a `ProxyJump` host is reached once per
+  master.
+- `~/.oats/ssh` (under `OATS_HOME_DIR` when set) is created mode 0700. OATS
+  does not use it if it is owned by another user or writable by group or
+  others.
+- ssh binds the control socket at the path plus 17 bytes, within the 104-byte
+  socket path limit of macOS, so the directory path may be at most 45 bytes.
+  `/Users/<name>/.oats/ssh` fits for any name up to 23 characters. The path
+  must also be one ssh reads literally: letters, digits and `. _ / + , : @ =
+  -` only (a space, `%`, `$`, a quote or `#` is ssh syntax).
+- When the path does not fit, has other characters, or the directory is not
+  private, calls run with `ControlPath=none` instead: no connection sharing,
+  including any your ssh config sets up; keepalives still apply. The command
+  warns once per server on stderr, naming the path and the fix (an
+  `OATS_HOME_DIR` or `HOME` that is shorter or plain).
+- A master left stale by a network drop is replaced by ssh on the next call.
+- The version probe (`oats version --json`) is asked once per process per
+  server and target. `server add --replace` to another target forgets it.
+- When ssh fails under an attached viewer (a lost link, or one never made),
+  `session attach --server` exits 255 and says that, if the link was lost,
+  the instance keeps running on the server, with the command to reattach.
+  When ssh fails before the viewer opens (the version probe, or a name
+  resolved through the host's roster), it also exits 255, with `oats: ssh to
+  <host> failed: …` (`--json`: the `E_SSH` envelope). Every other refusal
+  (an incompatible host, an unknown or ambiguous name, bad arguments) exits 1,
+  and so does an ssh that cannot be run on this machine at all: no link can
+  come back.
+- Every routed command reports ssh's own failure as `E_SSH` (`ssh to <host>
+  failed: …`). When ssh never started on this machine, the `--json` envelope
+  says so with `error.details: {"sshStarted": false}`; without details, ssh
+  ran and the link failed
+  ([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)).
+
 ## Run there
 
 ```bash
@@ -50,14 +96,18 @@ sent as text or on stdin, never as paths.
 |---|---|---|
 | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule |
 | `status` | registered workspace | |
-| `retire` | saved route | `retire-home` to retire by exact home |
-| `session inspect`, `session attach` | saved route | `session` |
-| `session start`, `session restart` | saved route | `session-start`; `session-restart`; `launch-config` when `--launch-config`, `--harness` or `--yolo` is given |
-| `session upload` | saved route | `session-upload` |
+| `retire` | the instance's home | `retire-home` to retire by exact home |
+| `session inspect`, `session attach` | the instance's home | `session` |
+| `session start`, `session restart` | the instance's home | `session-start`; `session-restart`; `launch-config` when `--launch-config`, `--harness` or `--yolo` is given |
+| `session upload` | the instance's home | `session-upload` |
 | `okf harvest --instance <name>` | the saved home | `harvest` |
 | `schedule ...` | registered workspace | `schedule` |
-| `launch-config list\|set\|remove\|preview` | `--dir`, a saved route, or the registered workspace | `launch-config` |
-| `inspect`, `operation run` | `--dir`, a saved route, or the registered workspace | `operations` |
+| `launch-config list\|set\|remove\|preview` | `--dir`, the instance's home, or the registered workspace | `launch-config` |
+| `inspect`, `operation run` | `--dir`, the instance's home, or the registered workspace | `operations` |
+| `readiness` | the instance's home, `--dir`, or the registered workspace | `readiness` (`readinessApi: 2`) |
+| `instance events` | the instance's home | `instance-events-2` (`eventsApi: 2`) |
+| `instance git`, `instance diff` | the instance's home; the Git runs there | `instance-git` (`instanceGitApi: 1`) |
+| `instance stop --plan\|--apply`, `retire --plan`, `retire --plan-revision … --idempotency-key …` | the instance's home | `lifecycle-plans` (`lifecycleApi: 1`) |
 
 Before every routed command except `status`, the kernel reads the server's
 `oats version --json`. A remote OATS older than 0.22.1 is refused, and so is a
@@ -66,19 +116,36 @@ checked against the harness it would use (the flag, or the soul's default as
 the remote roster reports it). A host that advertises no harness list is
 assumed to run only pi and claude, on tmux, with no launch options.
 
-**Addressing an instance.** Instance commands take `--instance <name>` (spawned
-from this machine) or `--home </remote/home>`. The home is the identity; use it
-when two souls on the host own same-named instances. A name and a home that
-disagree are refused (`E_HOME_MISMATCH`).
-
-**`--dir` with `--server`.** For `inspect`, `operation` and `launch-config`,
-an explicit `--dir` names a directory on the server and travels as is. Every
-other routed command refuses `--dir`; its scope comes from the registration.
+**Addressing an instance.** Instance commands (`retire`, the `session`
+commands, `inspect`, `operation`, `launch-config`) reach any instance on the
+server, whoever spawned it, by `--home </remote/home>` or by name
+(`--instance <name>`, or the positional name of `retire`):
+
+- A name spawned from this machine resolves through its saved route.
+- Any other name resolves through the server's roster (one `status --json`
+  in the registered workspace) to its one home. A name that two homes carry
+  there is `E_AMBIGUOUS`, listing the homes (`error.details.candidates`);
+  pass `--home`. A name the roster does not list is `E_SNAPSHOT_UNKNOWN`.
+- A `--home` no saved route owns is sent through the registration's target;
+  the server's kernel decides whether it is an instance home and its refusal
+  is relayed as is.
+- The home is the identity; use it when two souls on the host own
+  same-named instances. A name and a home that disagree are refused
+  (`E_HOME_MISMATCH`).
+
+**`--dir` with `--server`.** For `inspect`, `operation`, `launch-config`,
+`readiness`, `instance`, and a `retire --plan` or guarded retire apply, an
+explicit `--dir` names a directory on the server and travels as is. Every
+other routed command refuses `--dir`; its scope comes from the
+registration.
 
 **Not routed.** `session input` runs on the execution host, where schedules
 and messaging capabilities call it. `session restart --stop-grace` is refused
 with `--server`; the remote default applies. `session attach --print` shows
-the ssh command without running it.
+the ssh command without running it. A server without the `session` commands
+(before 0.22.2) is refused with the tmux command to attach there directly,
+naming the session and window its roster records for the instance (else
+`pi-agents`, that kernel's default).
 
 ## The roster and harvest
 
@@ -91,8 +158,13 @@ The **roster** is what the Desktop shows: one group per server id and route
 target (host and workspace), with the registration (present or not), the
 probe result, the remote souls, the instances joined with saved routes
 (`savedRoute`, `running` or `null` when unknown, `retirePending`,
-`rollbackIncomplete`, `missingRemotely`), and `retireFailures` (deferred
-self-retirements that failed there). A removed or edited registration keeps
+`rollbackIncomplete`, `missingRemotely`, `addressable`), and `retireFailures`
+(deferred self-retirements that failed there). Each instance row also relays
+the host's own facts from its `status --json`: `identity`,
+`identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
+`runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
+`relativeTo` and `spawnOrigin`. A fact the host does not supply is `null`
+(an older host, or a saved route the host no longer lists). A removed or edited registration keeps
 its group from the saved routes. State is pulled on every call within
 `--per-target` (default 20 s) of a total `--budget` (default 45 s); a group
 not reached is reported with `E_ROSTER_BUDGET`. `--server <id>` narrows it.
@@ -103,8 +175,8 @@ instance's saved home on the server and relays its envelope.
 ## What this machine keeps
 
 A **saved route** per remote instance, under `~/.oats/remote/<server>/`,
-written at spawn: the ssh host, workspace, oats path, optional Herdr path and
-PATH prefix, and the remote home. Retire, harvest and session commands use
+written at spawn: the ssh host, workspace, oats path and PATH prefix, and the
+remote home. Retire, harvest and session commands use
 the saved route, not the current registration, so editing or removing a
 registration never orphans a remote home. The route is removed when the
 remote kernel reports the home gone.
@@ -123,8 +195,5 @@ remote kernel reports the home gone.
 
 ## Limits
 
-- Lifecycle actions need a saved route from this machine. An instance the
-  remote reports but that was spawned elsewhere appears in the roster with
-  `savedRoute: false` and is read-only here.
 - No Git runs over SSH: repository operations always run on the server, by
   its kernel, in its deployment.

package/docs/souls-and-instances.md

@@ -29,6 +29,7 @@ that model.
 | Instance operating doc | `<home>/AGENTS.md` (generated) |
 | Instance skills | `<home>/.agents/skills/` |
 | Instance modules | `<home>/.oats/modules/<capability>/` (the copies this instance runs) |
+| Instance `oats` | `<home>/.oats/bin/oats` (a link to the kernel that last launched it) |
 | Instance record | `<home>/instance.json` (`modules`, `providers`, `workspace`, `teams`) |
 
 ## Soul anatomy
@@ -84,8 +85,8 @@ launch: { harness: claude, model: claude-opus-5-5 }   # optional (0.30): what th
 
 Schema: [`soul.schema.json`](soul.schema.json). Which teams a soul joins is the
 deployment's choice (`oats-local.yaml`, [workspaces.md](workspaces.md#teams)),
-and the backend, yolo and launch configuration are spawn-time host choices
-(`--backend`, `--yolo`, `--launch-config`, or a launch configuration in
+and yolo and the launch configuration are spawn-time host choices
+(`--yolo`, `--launch-config`, or a launch configuration in
 `oats-local.yaml`), not soul identity. The harness and model are a soul's
 *preference* at most (`launch:`), which each machine overrides and spawn flags
 (`--harness`, `--model`) win over.
@@ -126,6 +127,7 @@ full copy** of every capability the soul resolved to:
     <skill>/SKILL.md               # one level deep, where every harness discovers skills
   .claude/skills → ../.agents/skills
   .oats/modules/<capability>/      # the whole capability: oats.json, bin/, injects/, skills/ (hooks run from here)
+  .oats/bin/oats → <kernel>/bin/oats.mjs  # the kernel that last launched this home: first on the harness's PATH
   work/                            # worktree, checkout symlink, attached tree, or private directory
   TASK.md                          # briefing and task
   instance.json                    # provenance (below); `soulDir` = the soul directory hooks get as OATS_SOUL
@@ -244,7 +246,10 @@ it would bind, `providers` (the `--provider` map exactly as given) and
 the apply refuses with `E_DECISION_STALE` if a member
 moved in between. `--provider <cap> key=value` (repeatable; dotted keys nest)
 must name a capability the soul resolves (`E_CAPABILITY_MISSING` otherwise) and
-needs a workspace deployment. The full DTOs are in
+needs a workspace deployment. Spawn takes one soul and the flags it reads:
+another positional, or a flag it does not know, is `E_BAD_ARGS` naming the
+argument, before anything is created (a bare `key=value` is a provider
+setting given without `--provider <capability>`). The full DTOs are in
 [desktop-cli-api.md](desktop-cli-api.md#workspace-model-workspaceapi-2).
 
 Examples of spawn hooks:

package/lib/attachments.mjs

@@ -147,7 +147,8 @@ export function uploadAttachment({ file, home, server, instance }, io = {}) {
     if (!home) throw err("E_BAD_ARGS", "session upload needs --home </absolute/instance> or --server <id> with --instance <name> or --home");
     return { ...receiveAttachment(home, name, bytes, { maxBytes }), name, home: realpathSync(home), source: abs };
   }
-  const route = resolveRoute(server, { instance, home }, "session upload");
+  io = { ...io, serverId: server };
+  const route = resolveRoute(server, { instance, home }, "session upload", io);
   const remote = checkRemote(route.target, io);
   // Both lists must carry the token; a probe without the arrays is an old kernel.
   const advertises = (list) => Array.isArray(list) && list.includes("session-upload");