@awebai/oats 0.40.2 → 0.41.0

package/docs/execution-targets.md

@@ -55,11 +55,311 @@ 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.
+session it would open in, on the OATS tmux server (`E_INSTANCE_NAME_TAKEN`); a
+live window of that name in another session, such as a `pi-agents` window
+after the default moved, or on another tmux server, 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.
+
+<a id="the-oats-tmux-server"></a>
+#### The OATS tmux server
+
+OATS creates sessions on a tmux server of its own, named `oats`
+(`tmux -L oats`), not on your default tmux server, where earlier kernels
+created them. A tool that restyles the
+default server (a theme switcher, a script that runs `tmux set -g …` or
+`tmux kill-server`) therefore no longer reaches agent terminals.
+
+- **Where it is.** The server's socket is
+  `${TMUX_TMPDIR:-/tmp}/tmux-<uid>/oats`. The instance records the absolute
+  socket path it was created on, in `instance.json` and in the receipt, and
+  every later command uses that recorded path, never the name. OATS does not
+  compute the socket path and does not use `TMUX` to find a server: tmux
+  resolves the name once, when the session is ensured, from the
+  `TMUX_TMPDIR` of the process that runs OATS, which OATS passes on unchanged
+  when it replaces the environment for that call.
+- **Your configuration loads.** The server starts as any tmux server does, so
+  your `~/.tmux.conf` (key bindings, status line, options) applies to it.
+- **See what runs there:** `tmux -L oats ls`. Plain `tmux ls` and a bare
+  `tmux attach` show your default server, so they do not show the sessions
+  OATS creates now.
+- **Attach:** `oats session attach --home <home>`. By hand, copy the
+  `attach:` line that spawn prints: `tmux -S <socket> attach -t <session>`,
+  with the recorded socket. `tmux -L oats attach -t <session>` is a
+  convenience that holds only in an environment with the same `TMUX_TMPDIR`
+  as the one that created the session.
+- **`TMUX_TMPDIR`.** Two environments with different values (a login shell,
+  and a process started by a service manager or launchd, a schedule runner or
+  a GUI launch) each get their own `oats` server. Every instance stays
+  reachable, because its absolute socket is recorded.
+- **A limit.** A tool that runs inside a pane of the OATS server has `TMUX`
+  pointing at that server and still reaches it.
+
+**What OATS sets, and at which scope.** OATS sets nothing server-global on any
+server when it creates a session or a window, and nothing at all on a server
+other than the one the window is on.
+
+| On | OATS sets | Scope |
+|---|---|---|
+| each agent window it creates | `window-style default`, `window-active-style default`, `cursor-colour default` | that window (`set-option -w`), by window id |
+| each agent window, and the `hq` window of a session it creates | `window-size latest`, `aggressive-resize on` | that window |
+| the pane of each window it launches a harness in, and a pane it respawns in place | no `COLORFGBG` in the pane's environment | that pane's command |
+
+So an agent pane takes the colours of the terminal that views it, whatever
+the server's own defaults say, and on tmux 3.1 or later the window follows
+the size of the viewer that used it last. A window that is restarted in place
+keeps the options it has. A session OATS did not create, and the server's global
+options and environment, are left exactly as they were.
+
+- `pane-colours` (the palette) is not reset: a local reset did not neutralise
+  inherited array entries, so OATS leaves the palette alone. A configuration
+  that sets `pane-colours` globally therefore reaches agent panes. It comes
+  from your own tmux configuration, which OATS loads on purpose: remove the
+  setting there, or unset it on the running server with `tmux -L oats
+  set-option -gu pane-colours`.
+- The oldest supported tmux stays 3.0. On tmux 3.0 and 3.0a `window-size
+  latest` is not available and is skipped, as before this change;
+  `cursor-colour` is skipped below 3.3; no error in either case. On 3.0 and
+  3.0a the window therefore keeps the sizing that server gives it, not the
+  latest viewer's.
+- The two sizing commands are each attempted on their own, and a refused one
+  is ignored: the launch goes on. Nothing else is tolerated: a refused
+  `window-style` or `window-active-style` is a launch failure (the spawn is
+  rolled back and fails; a start fails with `E_SESSION_START_FAILED`). An
+  earlier kernel failed a start whose recorded tmux server could not be
+  reached when a sizing command was refused; this one does not.
+
+<a id="the-servers-start-environment"></a>
+#### The environment of the server and its panes
+
+A tmux server keeps the environment of the process that started it, as its
+global environment. A pane gets that, plus its session's environment (the
+variables tmux's `update-environment` names, taken from whoever created the
+session), plus what the launch command sets (`OATS_INSTANCE`,
+`OATS_INSTANCE_HOME`, the capabilities' and the launch configuration's
+variables). One variable is different: **a pane's `PATH` is the `PATH` of the
+process that creates its window**, that is of each `oats spawn` or `oats
+session start`, with the home's own `oats` shim put first by the launch
+command. So:
+
+- `PATH` follows the process that runs each spawn or start, not whoever
+  started the server.
+- The rest of the ambient environment follows the server's first creator,
+  and a server that already runs keeps what it started with. Creating a
+  session or a window on it changes nothing global.
+
+Who starts the `oats` server, after an install, a reboot or its last session
+ending, decides that ambient environment:
+
+| Started by | The server's environment |
+|---|---|
+| an operator's shell | that shell's |
+| the Desktop | your environment as the Desktop got it, without what the Desktop or its packaging added to its own, and with the login-shell `PATH` it puts in front ([desktop.md](desktop.md)) |
+| a schedule runner or a trigger | the service's |
+| an OATS instance that creates an agents' session | the global environment of the tmux server that instance's home records, reduced as described below; not the instance's own |
+
+The first creator that succeeds determines it; when two start it at the same
+moment, tmux starts one server and nothing says which of the two it is.
+
+**What OATS removes, for every creator.** The names the kernel itself sets
+never go into the environment OATS creates an agents' session or window
+with: `COLORFGBG`, `TMUX`, `TMUX_PANE`; the launch identity and roots
+(`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, `OATS_HOME`, `OATS_AGENT`,
+`OATS_SOUL`, `OATS_SOUL_ID`, `OATS_ROOT`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
+`OATS_EVENT`, `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`,
+`PI_AGENT_INSTANCE`, `PI_AGENT_HOME`, `PI_AGENTS_ROOT`); what a hook, an
+operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
+`OATS_LEVEL`, `OATS_META`, `OATS_DEPLOYMENT`, `OATS_RESOLUTION`,
+`OATS_OPERATION`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`, `OATS_KIND`,
+`OATS_TASK`, `OATS_HARNESS`, `OATS_PREVIOUS_HARNESS`, `OATS_RUNTIME`,
+`OATS_PREVIOUS_RUNTIME`, `OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
+`OATS_TRIGGER_EVENT_FILE`, `OATS_TEAM_NAME`, `OATS_TEAM_SCOPE`,
+`OATS_TEAM_ID`, `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS`, `OATS_TEAMS`,
+`OATS_TEAMS_SOURCE`, `OATS_DEFAULT_TEAM`, `OATS_DEFAULT_TEAM_ID`,
+`OATS_DEFAULT_TEAM_FROM`, `OATS_WORKSPACE_NAME`, `OATS_WORKSPACE_KEY`); and
+every launch reference (`OATS_LAUNCH_REF_<NAME>`) with the `<NAME>` it stands
+for. Other `OATS_` variables you export (`OATS_HOME_DIR`,
+`OATS_TMUX_SESSION`) are yours and stay. An agent's plain `oats` finds its
+deployment from its home.
+
+**An instance creates an agents' session or window without its own
+environment.** Nothing of an instance's environment reaches a server or a
+pane through the calls that create an agents' session or window. A harness
+puts its own variables, credentials and identity into the environment of
+what it runs. A process is inside an instance when `OATS_INSTANCE_HOME` names an instance
+home, or its working directory is inside one. That covers an agent that
+spawns or starts another instance, a capability hook that spawns or starts
+(a hook runs with its instance's identity, also when a person ran the command
+that triggered it), and `oats schedule run-now` typed inside an instance.
+
+- When such a process has to create the tmux session, OATS reads the global
+  environment of the server its home records (`tmux -S <recorded socket>
+  show-environment -g -s`, the endpoint of the home's receipt, checked
+  against `instance.json` as every session command checks it) and creates
+  the session with that. What the new session gets is a reduction of that
+  environment, not an exact copy. It is read strictly and never run by a
+  shell; text that cannot be read to its end is a failed read. Not carried
+  from the recorded server:
+  - a hidden or removed variable;
+  - a variable whose value holds a line break;
+  - a variable whose value holds a `$`: tmux versions print it differently,
+    so OATS does not guess what the value was;
+  - on tmux 3.4 and 3.5, a variable whose value holds a control character or
+    a byte that is not UTF-8, which those versions print encoded. Other
+    versions print the line as it is: there a control character other than
+    a line break is carried exactly, and a byte that is not UTF-8 fails the
+    read.
+
+  Such a variable is absent in the panes of the new server unless the pane's
+  own shell start-up files set it; it is never filled in from the instance's
+  own environment. When the variable left out is one that decides which
+  configuration a tmux server loads or which programs it runs (`HOME`,
+  `XDG_CONFIG_HOME`, `PATH`, `SHELL`), the creation is refused instead, with
+  the same remedy as below.
+- When it creates a window in a session that exists, the tmux client that
+  creates it runs with `PATH`, without any instance's `oats` shim directory,
+  and with `LANG`, `LC_ALL` and `LC_CTYPE`, which that client needs to start
+  on a host whose only UTF-8 locale is the one they name. tmux hands a pane
+  the `PATH` of that client and nothing else of it: the three locale names
+  stay with the client, and the pane, the session and the server keep the
+  values they had. Nothing else of the instance travels. When the instance
+  has no `PATH` to give (none is set, or only `oats` shim directories were
+  in it), none is passed: the pane then takes no `PATH` from the client. A
+  restart that reuses the pane the home already has runs its tmux client
+  with the same environment; where and whether the pane is reused does not
+  change.
+- **It is refused** (`E_RUNTIME_ENDPOINT_UNKNOWN`; `oats spawn` reports it
+  as `E_SPAWN_FAILED` with the same message) when the session does not exist
+  on the `oats` server and there is no source to read: the home records no
+  tmux server (it was never launched), its receipt cannot be used, or its
+  recorded server cannot be reached or read. A process that carries an
+  instance's identity (`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, `OATS_HOME`,
+  `PI_AGENT_INSTANCE` or `PI_AGENT_HOME`) with no home to be found is refused
+  the same way. Nothing falls back to the caller's environment, to another
+  server or to a built-in list.
+- **When the refusal comes.** In `oats spawn`: before any scaffold, work
+  tree, identity or hook. In `oats session start`: after the start's
+  preflights and its planning, and before the real run of preview-aware
+  launch hooks, a stop and any write of the home's launch state (its record,
+  its receipt, a pending start). A launch hook that does not declare
+  `launchPreview` has already run by then, and a warning it returned is
+  already a `launch-warning` event of the home, as before any other late
+  refusal of a start (`E_SESSION_RUNNING`, `E_LAUNCH_ENV_MISSING`). Nothing
+  undoes what that hook did, and there is nothing to clean up: a launch hook
+  may do idempotent provider registration on a real start and no more
+  ([capabilities.md](capabilities.md)), so the next start repeats it
+  harmlessly. Both launch hooks OATS ships are preview-aware. If the
+  session disappears between that check and the creation, the refusal comes
+  at the creation, and the spawn is rolled back as any failed launch is.
+- **The remedy** is to create the session from your own shell, outside every
+  instance home, as below. The session name matters: it must be the
+  deployment's (the refusal names it); another deployment's session on the
+  same server does not help. Once the session exists, the instance spawns
+  and starts there without reading anything.
+- The recorded server's environment is an existing baseline, chosen because
+  it is what a window that instance opened on that server got. It is not
+  proof that it holds no old identity or credential, and this is not a
+  promise that secrets are isolated between instances that run as the same
+  user on one tmux server.
+- A server that already runs keeps its baseline. OATS creates sessions and
+  windows on it and does not certify where that baseline came from or that
+  it is clean: someone who started a server named `oats` by other means
+  decided it.
+- These rules are about the calls that create an agents' session or window,
+  nothing wider. `oats session attach` creates a temporary viewer session on
+  the server the home records, with the attaching process's own environment
+  ([#623](https://github.com/awebai/oats/issues/623)): tmux imports the
+  `update-environment` names into that temporary session, and if that
+  server exits between the viewer's check and its creation, the attaching
+  process is the one that starts it.
+- Which server is reached is decided by the process that creates, never by
+  the environment it passes: its own `tmux`, its own `TMUX_TMPDIR`, and the
+  socket the lookup returned when the server runs. Its own `tmux` is the one
+  its own `PATH` finds, and the session is created by that program's full
+  path. A process whose `PATH` holds no tmux cannot read the server at all:
+  it is refused (`E_RUNTIME_ENDPOINT_UNKNOWN`) whether or not the session
+  exists, and told to run the command with a `PATH` that holds tmux. A
+  process whose `PATH` is not set is refused only when it has to create the
+  session (tmux used to be found by the system's default search then); with
+  the session already there, it is not refused. What the server process
+  gets (`HOME` and so which configuration loads, `PATH`, everything else)
+  comes from the passed environment alone. The global environment of the
+  server the session is created on is never read for this and never changed;
+  the one that is read is the recorded server's, as above.
+
+A process that neither sign identifies as an instance is treated as any
+other creator: its environment, without the names above, is what it passes.
+
+By hand (`<session>` is the deployment's session name: `oats-agents` unless
+`session.tmuxSession` or `OATS_TMUX_SESSION` says otherwise):
+
+```sh
+tmux -L oats new-session -d -s <session> -n hq   # start it from your own shell, before anything else does
+tmux -L oats show-environment -g                 # what environment the server has
+tmux -L oats show-environment -g LANG            # one variable
+tmux -L oats set-environment -g LANG "$LANG"     # repair a running server: windows created from now on inherit it
+tmux -L oats kill-server                         # replace it: ends EVERY session on that server
+```
+
+- Start it yourself after an upgrade or a reboot, before agents, the Desktop
+  or a schedule run. OATS finds a session you created and uses it: it looks
+  the session up by its exact name and assumes nothing about its `hq`
+  window.
+- `set-environment -g` is how a running server is repaired: it ends nothing,
+  and panes that already run keep the environment they have. A pane's `PATH`
+  is always that of the process that runs the spawn or the start, so setting
+  `PATH` on the server changes nothing for OATS panes.
+- `kill-server` ends every session on that server, every running agent
+  included. It is for before agents are started, not for repairing a running
+  host. The next start takes the environment of whoever starts it.
+- `-L oats` reaches the server of the environment you type it in
+  (`TMUX_TMPDIR`). For the server an instance is on, use the socket from its
+  row in `oats status --json`: `tmux -S <socket> …`.
+- A tmux server whose socket file is missing or does not answer reads as not
+  reachable, which is not proof that it exited: status, start and stop read
+  that state as stopped
+  ([#624](https://github.com/awebai/oats/issues/624)). That is an existing
+  limit of every tmux server OATS uses, not of the `oats` server in
+  particular.
+
+<a id="existing-instances"></a>
+#### Existing instances
+
+Upgrading moves nothing. An instance launched by an earlier kernel stays on the server
+it recorded (usually your default one), and status, inspect, input, attach,
+stop and retire keep acting on that recorded socket. While a deployment has
+both, look at both servers: `tmux ls` and `tmux -L oats ls`.
+
+- A restart in place stays on the recorded server: a live harness that is
+  restarted, a fallback shell or a dead pane is reused where it is, and the
+  record does not change.
+- **Changed:** a start that has to create the window again, because the
+  recorded window is gone or the recorded server cannot be reached, creates
+  it on the OATS server. Earlier kernels recreated it on the recorded socket.
+  The start records the new socket in `instance.json` and the receipt, and
+  says so: one line in its `warnings`, naming the instance, the old socket
+  and the new one, and the same text as a `launch-warning` instance event.
+- A home that was never launched (`--no-launch`) starts on the OATS server,
+  with no warning.
+
+To move a running instance deliberately:
+
+```sh
+oats instance stop <instance> --plan     # then run the `apply with:` line it prints
+tmux -S <recorded socket> kill-window -t '=<session>:=<instance>'
+oats session start --home <home>
+```
+
+The socket and the session are the `tmux.socket` and `tmux.session` of the
+instance's row in `oats status --json`. The stop leaves a fallback shell in the
+window, which a start would reuse in place; closing the window is what makes
+the start create a new one.
+
+Do not end the agents' session by hand (`tmux kill-session`): that ends every
+other instance whose window is in that session, not only the one you are
+moving. And a window that a viewer still links would live on in that viewer,
+so the next start would create a second window for the same home.
 
 ### Herdr (removed in 0.31.0)
 
@@ -99,16 +399,19 @@ saved route that records `herdrPath` still loads; the field is ignored.
 ### Start and restart
 
 `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; a `--no-launch` home starts on the default tmux
-server.
+spawn hooks and creates no new home. It runs the recorded launch recipe in the
+recorded tmux session. A window that is still there is reused on its recorded
+server; a window that has to be created, a `--no-launch` home's first one
+included, opens on [the OATS tmux server](#the-oats-tmux-server).
 
 - `--model`, `--launch-config <name>|none`, `--harness` and `--yolo` /
   `--no-yolo` re-resolve the recipe against the home's recorded context and
   run every check before anything starts. `--model` replaces the recorded model
   for this and later starts.
 - A live harness is refused (`E_SESSION_RUNNING`). A fallback shell or a dead
-  pane is reused in place; a missing window or a lost tmux server is recreated.
+  pane is reused in place. A missing window, or one whose tmux server cannot
+  be reached, is created again on the OATS tmux server, and the start warns when that is
+  not the server the home recorded ([Existing instances](#existing-instances)).
 - A state that cannot be established is refused (`E_SESSION_UNKNOWN`). Two
   starts of one home serialize (`E_SESSION_START_BUSY`). A home being retired
   is refused (`E_INSTANCE_RETIRING`).

package/docs/implementation.md

@@ -284,14 +284,25 @@ scaling by call count.
 
 Locally, run the suites your change affects, plus `validate` and `check`; run
 `smoke:tarball` when you change the smoke script or packaging. Pull-request CI
-runs the full suite (sharded), `check`, `validate`, `pack:check` and the smoke
-test, and is the gate. Tests use local bare repositories and fakes; none
-contacts GitHub, aweb, Jira or Linear.
+runs the full suite (sharded), the Desktop suite again with only Desktop
+dependencies installed, `check`, `validate`, `pack:check` and the smoke test,
+and is the gate. Tests use local bare repositories and fakes; none contacts
+GitHub, aweb, Jira or Linear.
 
 Desktop's standalone tests (`cd packages/desktop && npm ci && npm test`) must
-load with only Desktop dependencies installed. Cross-package tests that import
-both the kernel and Desktop belong under root `test/`; install dependencies at
-the root and in `packages/desktop` before running those tests. The schedule
+load with only Desktop dependencies installed. The release builds Desktop that
+way: its `desktop-build` job installs and tests inside `packages/desktop` and
+never installs the root. The sharded suite installs the root first, so a
+Desktop test that reaches a root-only dependency passes there and would fail
+only at a tag. Pull-request CI therefore has a `desktop-standalone` job that
+runs the same `npm ci` and `npm test` inside `packages/desktop` with no root
+install, and the gate requires it. `test/continuous-integration.test.mjs` pins
+that job against `desktop-build`: change how one installs or tests Desktop and
+the other changes with it.
+
+Cross-package tests that import both the kernel and Desktop belong under root
+`test/`; install dependencies at the root and in `packages/desktop` before
+running those tests. The schedule
 round-trip case is `node --test test/desktop-schedule-roundtrip.integration.mjs`.
 The root runner includes this file with its existing Desktop dependency group.
 With only root dependencies installed, it omits both Desktop suites and this
@@ -316,3 +327,23 @@ which fails with `ENOTEMPTY` (awebai/oats#451). So:
   it runs there.
 
 Never paper over such a race with a retry around the cleanup.
+
+A test never reaches the operator's tmux. The kernel creates sessions on the
+server named `oats` (`tmux -L oats`), which tmux resolves under `TMUX_TMPDIR`,
+and acts on every existing session through its recorded socket
+([execution-targets.md](execution-targets.md#the-oats-tmux-server)). So:
+
+- A test that runs real tmux installs `isolateSessionEnvironment(base)`
+  (`test/helpers/host-fixture.mjs`). It owns a private, short `TMUX_TMPDIR`
+  (socket paths are limited to about 104 bytes) and puts a `tmux` wrapper
+  first on `PATH` that admits only `-L oats` and `-S` of a socket inside the
+  fixture, with no user configuration unless the test asks for it;
+  `oatsSocket()` is the socket `-L oats` resolves to there. Its restore
+  function kills that server, by socket.
+- The shared fixture (`test/helpers/v2-deployment.mjs`) gives every command
+  it runs a private `TMUX_TMPDIR` too, so a test with a fake `tmux` on `PATH`
+  cannot reach a real server either. A fake answers what the kernel asks:
+  `list-sessions`, `new-session` (it prints `<socket>\t<window id>`),
+  `list-windows`, `new-window` (a window id) and `set-option`.
+- A server a test starts is killed by its socket, never by name and never
+  with a bare `tmux kill-server`.

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

@@ -0,0 +1,238 @@
+# OATS 0.41.0
+
+## Changed
+
+- **The framework workspace has a separate maintainer soul.** The new
+  `oats-maintainer` soul is the OATS maintainer: direction, the roadmap,
+  architecture coherence, routing work to experts, review, merge and releases.
+  It composes `oats.maintainer` and carries the OATS-only `/oats-pr-review` and
+  `/git-tag-release` skills. `oats-expert` stays an expert, the generalist that
+  leads cross-area work, coordinates the domain experts and reports to
+  `oats-maintainer`. The other souls send direction, contract decisions and
+  merges to `oats-maintainer`, and read its knowledge node
+  (`oats/oats-maintainer`, which holds what the `oats-expert` node held).
+  - The `oats` knowledge store's main must declare the `oats-maintainer`
+    node before this reaches a deployment: souls that read or own it fail
+    their knowledge check with `E_CONFIG unresolved node:
+    oats/oats-maintainer` against a base without it.
+  - Operators: `oats sync`, then spawn `oats-maintainer` for maintainer work.
+    Running instances keep what they were spawned with.
+- **Desktop terminals keep text readable (#602).** Desktop terminals now keep
+  text at a contrast of at least 4.5:1 with its background, so coloured text written for
+  another palette (a grey meant for a dark terminal, shown in White) stays
+  readable. The built-in palettes' colours on the terminal background are
+  unchanged; text on a coloured background may be drawn lighter or darker than
+  the program asked.
+- **Desktop can match this computer's theme (#602).** A fourth theme choice,
+  **This computer**, shows Desktop's chrome and every terminal in the theme of
+  the computer that runs Desktop. On an Omarchy computer that is the current
+  Omarchy theme, followed when it changes, with no restart. Elsewhere it is
+  Dark or White by the system's appearance. Text colours taken from the host
+  are adjusted where needed to stay at least 4.5:1 on Desktop's surfaces; a
+  terminal's 16 colours are the host's own. If the host's theme cannot be
+  read, Desktop shows Dark or White and says so. A theme you chose does not
+  change: choose **Theme: This computer** in the command palette, or cycle to
+  it with the theme button.
+  - On an Omarchy computer Desktop reads the theme's colours file at start and
+    each time a window gets focus, whichever theme is chosen. It opens the file
+    without blocking and reads it only if it is a regular file, so a colours
+    file replaced by a named pipe, for example, cannot hang it (#612).
+  - On Linux, This computer is the default: a Desktop where no theme was ever
+    chosen starts in This computer (the computer's Omarchy theme, or the
+    system's light or dark appearance where there is none) instead of White.
+    That includes an existing install where the theme was never changed. If
+    you chose White at any time, it stays White. Choose another theme with the
+    theme button or the palette, and it stays. On other platforms the default
+    is still White.
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.42.0`**, so it runs against
+  this release's kernel; the Desktop 0.40.x refuses a 0.41 CLI.
+- **Desktop's Remove has one choice, the worktree.** Remove no longer offers
+  to delete a branch: retirement leaves branches to the operator, and the
+  kernel refuses the flag. The dialog's one choice is **Also delete the
+  worktree**, and it says "Remove never deletes a branch." A home left by a
+  failed spawn that still owes its branch stays incomplete while that branch
+  exists, and Remove can no longer complete it: check the branch and delete it
+  with Git, then remove the home again.
+- **New sessions run on an OATS-owned tmux server (#602).** The server is
+  `tmux -L oats`, so tools that restyle the default tmux server no longer
+  reach agent terminals. Running instances stay where they are. Plain
+  `tmux ls` and `tmux attach` no longer show new sessions: use `oats session
+  attach` or the `attach:` line that spawn prints. An existing instance moves
+  only when its window is recreated: a start after its window is gone or its
+  tmux server cannot be reached now opens on the OATS server instead of the
+  recorded socket. To move one deliberately, stop it, close its window and
+  start it: see
+  [Existing instances](../execution-targets.md#existing-instances).
+  - Operators: after upgrading, and after a reboot, start the `oats` server
+    from your own shell before anything else does: `tmux -L oats new-session
+    -d -s <session> -n hq` (`<session>` is the deployment's session name,
+    `oats-agents` by default). A tmux server keeps the environment of whoever
+    starts it: without this step the first Desktop-run or scheduled spawn
+    decides the ambient environment of later panes, and a spawn or start run
+    from inside an instance whose own tmux server cannot be read is refused
+    ([the environment of the server and its panes](../execution-targets.md#the-servers-start-environment)).
+  - Nothing of an instance's environment reaches a server or a pane through
+    the calls that create an agents' session or window: an instance creates
+    the session with a reduced copy of the environment of the server its
+    home records (a variable whose value holds a `$`, a line break or a
+    character tmux prints encoded is not carried), and a window with only
+    `PATH` and the locale names tmux's client needs
+    (`LANG`, `LC_ALL`, `LC_CTYPE`), which tmux does not hand on. Every
+    creator's environment goes without the names the kernel sets
+    (`OATS_INSTANCE`, `OATS_ROOT`, `PI_AGENTS_ROOT`, launch references and
+    the others the docs list). A server that already runs keeps the
+    environment it has: OATS does not certify where that came from.
+  - On each agent window it creates, OATS resets `window-style`,
+    `window-active-style` and `cursor-colour` to `default`, and removes
+    `COLORFGBG` from the pane, so the pane shows the colours of the terminal
+    that views it. It does not reset `pane-colours`: a palette set in your
+    tmux configuration still reaches agent panes
+    ([what OATS sets](../execution-targets.md#the-oats-tmux-server)).
+  - OATS sets nothing server-global on any server when it creates a session
+    or a window. `window-size latest` and `aggressive-resize on`, which it
+    used to set globally on the server it created its session on, are now set
+    on the windows it creates.
+  - The spawn result's `attach` is `tmux -S <socket> attach -t <session>` for
+    a launched spawn and `oats session attach --home <home>` for
+    `--no-launch`; a routed spawn (`--server`) prints `oats session attach
+    --server <id> --instance <instance>`. The JSON shapes are unchanged.
+  - The kernel no longer exports `launchEnvTmuxFlags` (it had no consumer).
+
+## Upgrade
+
+**Retirement no longer deletes branches.** What to do:
+
+- **`oats retire --delete-branch` is refused** with `E_BAD_ARGS` before
+  anything happens: no child or session is stopped, no hook runs, nothing is
+  written. Retire without it; the branch is left in the repository. Inspect it
+  there and delete it with Git if it is no longer wanted. Scripts that pass the
+  flag must drop it. A self-retire an older OATS recorded with the flag is
+  completed with the branch and the worktree left, and its `retired` event says
+  so.
+- **A home a failed spawn left that still owes its branch** stays incomplete
+  while that branch exists, with the item `the branch the failed spawn created
+  is left: OATS does not delete it. Inspect it and delete it with Git if it is
+  not wanted, then retry`. The item names no branch; the CLI prints it on the
+  next line (the receipt's `retention.recordedBranch`, or the `branch` in the
+  retained home's `instance.json` when the worktree step did not run). While
+  Git cannot show the branch gone, the item is `git branch <b>: could not
+  verify whether it still exists (…)`. Delete the branch with Git, then retire
+  again.
+- **A worktree whose branch has no commit yet:** `oats retire
+  --discard-worktree`, or a retire that has work to copy, on such a worktree
+  refuses with `E_WORK_INSPECTION_FAILED` and removes nothing. Make a commit,
+  switch the worktree to a branch that has one, or remove the worktree with
+  Git; then retire again.
+- **A worktree Git refuses to read without your own `safe.directory`**
+  (typically one owned by another user) now refuses a retire that has work to
+  preserve or that removes the worktree, with `E_WORK_INSPECTION_FAILED`. A
+  plain retire of such a worktree with nothing to preserve retains it under a
+  `detached-unknown` name, without its branch in the receipt. Retire as the
+  owner, or with Git's ownership check satisfied for that path.
+
+## Fixed
+
+- **A retire keeps what only the worktree has.** The recovery a retire writes
+  of a worktree is proven against the commit the worktree has checked out, and
+  is checked out at that commit on the worktree's own branch (detached, when
+  the branch's name is not one OATS carries). A clean worktree whose HEAD is
+  detached at a commit no ref of the repository reaches is preserved in a
+  recovery before `--discard-worktree` removes it, also when a retire hook made
+  that commit. HEAD is read again immediately before the worktree is removed:
+  if it moved since the retire's last inspection, the worktree is not removed
+  and the retire stops with `E_WORK_PRESERVATION_FAILED`; the home and the
+  worktree are kept, and so is any recovery the retire wrote.
+- **A stopped instance's harness mark is readable in Solarized (#602).** In
+  the Desktop's roster, the harness mark of a stopped instance was drawn at
+  4.0:1 in Solarized, under the 4.5:1 the rest of the app keeps. It is now
+  4.7:1. The mark's block is slightly lighter in White and Solarized and
+  slightly darker in Dark.
+- **Review threads reach an agent whose session is not on the default tmux
+  server (#602).** Sending a pull request's review threads to an agent's
+  terminal from the Desktop now uses the tmux socket the instance records, as
+  the Desktop's terminals do. Before, the paste always went to the default tmux
+  server: for an instance that records another socket it answered that the
+  paste failed, or it could go into a window of the same name on the default
+  server. An instance that records no socket is pasted to as before.
+- **The Desktop names a retire refused at inspection.** When `oats retire`
+  refused a local instance with `E_WORK_INSPECTION_FAILED`, the Remove dialog
+  said "The lifecycle CLI is unavailable.", although the CLI had answered. It
+  now says: "Retirement was refused: the instance's home or work could not be
+  inspected. The home is kept; its session may already have been stopped, and
+  earlier retirement steps may have run." The outcome is still reported as
+  unknown, because the kernel can refuse after it stopped the children and the
+  session and ran the retire hooks. For an instance on a server the same
+  sentence replaces that headline, above the host's own message in Details.
+  For a local refusal the CLI's own message, which names the path and the
+  remedy, is in Details too (next entry). Part of
+  [#601](https://github.com/awebai/oats/issues/601).
+- **The Desktop shows the kernel's own message when a local Stop or Remove
+  fails.** The dialog said only its own sentence for the error code; the
+  message the CLI answered with was dropped. It is now in the dialog's
+  **Details**, as the code and the message, under that sentence, as it already
+  was for an instance on a server. It is shown only when the installed CLI
+  answered with an error and the Desktop has a sentence for its code: a
+  timeout, an unreadable answer or an unknown code shows none. Closes
+  [#601](https://github.com/awebai/oats/issues/601).
+- **The Desktop shows a kernel or host message as one plain line.** In the
+  Details of a refusal (Stop and Remove, the Git panel, Activity, readiness),
+  line feeds, the Unicode line and paragraph separators and tabs are collapsed
+  into single spaces. The C1 control characters, the bidirectional embedding,
+  override and isolate characters, the zero-width space, the word joiner, the
+  byte order mark and tag characters are each replaced by U+FFFD, the
+  replacement character. A message that holds a carriage return, DEL or
+  another ASCII control character other than tab and line feed (a message
+  with Windows line endings, for example), or that looks like a credential,
+  is withheld whole as `[Detail withheld]`, as before. A long message is cut
+  at 2048 characters. For readiness, the message is no longer in the "Couldn't
+  refresh" line's tooltip, which keeps the Desktop's sentence and the error
+  code; it stays in Details. In the Git panel a failed read's message, which
+  could span several lines, is now one line.
+- **A tmux server started from the Desktop gets your environment, not the
+  Desktop's (#602).** A tmux server started from the Desktop (by a spawn or a
+  start, or by opening a terminal) no longer carries the Desktop's own runtime
+  settings. They made Electron programs started from an agent's pane run as
+  Node, and on the AppImage they pointed library and data paths into the
+  Desktop's mount, which exists only while that Desktop runs. Every program
+  the Desktop starts (the `oats` CLI, `tmux`, `gh`, the login shell that
+  resolves `PATH`) now gets your environment without them. One change in a
+  diagnostic: `probePath` in the backend's `GET /api/cli` answer no longer
+  lists the AppImage's own entries. A tmux server that was already running
+  keeps the environment it was started with (#616). Known limits are in the
+  Desktop README.
+- **The Desktop builds a view's failure placeholder as text.** A tab whose
+  view fails to load or to mount shows the same words, built without markup.
+- **`oats retire` no longer refuses a launched instance only because its
+  tmux socket file is missing.** After a reboot that cleared tmux's socket
+  directory, tmux answers `error connecting to <socket> (No such file or
+  directory)` for the socket the instance's session was recorded on, and
+  retire refused with `E_RUNTIME_QUIESCE_FAILED`. Retire now goes on when the
+  recorded server cannot be reached because its socket file is missing and no
+  process on the host works in the instance's home (any process whose working
+  directory is in the home, not only the harness). A tmux server keeps running
+  when its socket file is removed, so when a process still works in the home,
+  or the process scan (`lsof`) cannot run or does not complete, retire refuses
+  as before and the message says which. Such a server recreates its socket
+  when its process is sent `SIGUSR1`. The check needs `lsof`: on a host
+  without it, a retire whose recorded socket file is missing is still refused,
+  and the message says that `lsof` is missing; install it, then retire. The
+  scan counts only when `lsof` completed: one that was cut off (a timeout, too
+  much output, a signal) is no longer read as "no process", here, for a home
+  without its session receipt and for a home opened in Herdr; those retires
+  are refused. So is one whose listing names no process at all, which a
+  completed scan never prints. A window that is still running, or a server
+  that cannot be read for another reason, is refused as before.
+  [#620](https://github.com/awebai/oats/issues/620).
+
+## Removed
+
+- **Three unused routes of the Desktop's local server.**
+  `GET /api/session/<instance>` (a capture of the instance's terminal),
+  `POST /api/keys/<instance>` (keys or a paste typed into it) and
+  `POST /api/interrupt/<instance>` (Ctrl-C) are gone. Nothing in the Desktop
+  used them: its terminals attach to the instance's session directly. They
+  ran `tmux` without the socket an instance records, so for an instance on
+  its own tmux server they would have reached another one. Each path now
+  answers as any unknown route does (`404`, `not found`).
+  `GET /api/chat/<instance>` is unchanged. Closes
+  [#609](https://github.com/awebai/oats/issues/609).

package/docs/servers.md

@@ -277,7 +277,10 @@ with `--server`; the remote default applies. `session attach --print` shows
 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).
+`pi-agents`, that kernel's default), and the tmux socket when the roster
+records one. The remote command is one quoted word either way: `ssh -t
+<host> 'tmux attach -t <target>'`, or `ssh -t <host> 'tmux -S <socket>
+attach -t <target>'`.
 
 ## The roster and harvest