@awebai/oats 0.40.1 → 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`).
@@ -143,35 +446,36 @@ oats session attach --home /abs/home
   live claim that the instance needs input from a human, `{since, producer,
   reason, message}`, or `null`; it is non-null only for a running harness
   (docs/desktop-cli-api.md, "Waiting on you").
-- **input** submits UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
-  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. The text is pasted once. Enter waits for the pane to
-  settle (two identical captures, at least about 200 ms, longer for a larger
-  paste, at most 2 s), and is judged by whether it changed the bottom 15 lines
-  of the pane. The comparison is of bytes only, and the pane's text is never
-  interpreted. Trailing spaces are ignored. When the pane was seen to change
-  size (a resize, or a second client attaching), a reflow of the same content
-  is not a change either: each side's content must already be on the other
-  side's screen or in its history, so content that appeared or disappeared
-  still counts. An Enter that changed nothing was swallowed, and is resent
-  after a backoff, at most 3 Enters in total. The answer adds:
-  - `submitted: true, verified: true`: an Enter was taken.
-  - `submitted: false, verified: true, reason: "enter-not-taken"`: none of the
-    3 Enters changed the pane. The text stays in the agent's input box; it is
-    not pasted again.
-  - `submitted: true, verified: false`: a capture failed, so no further Enter
-    was sent and the last one was not judged. As before, this means the
-    terminal accepted the keys. When the pane cannot be read before the first
-    resend, exactly one Enter was sent.
-
-  `submitted` never means the agent processed the text. A pane that changes
-  for another reason after Enter (a spinner, a clock, a human typing) reads as
-  taken. A harness that shows no visible reaction to Enter receives up to two
-  extra Enters; real harnesses (claude, codex, pi) redraw on submit. A call takes at most about 4 s plus its tmux calls. A failed paste or
-  key send is `E_SESSION_INPUT_FAILED`, with no retry. Wake schedules and
-  messaging capabilities use this command ([schedules.md](schedules.md)); a
-  wake schedule records any answer as delivered.
+- **input** sends UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
+  NUL) as exactly one bracketed paste followed by exactly one Enter. The text
+  is never run by a shell. Existing endpoint authority, fallback-shell,
+  stopped-session and split-window checks still refuse before input.
+
+  Before Enter, a size-based floor (200 ms plus 3 ms per KiB) and read-only
+  settling polls share one **monotonic 2-second observation budget**, starting
+  immediately after the paste command returns, before buffer cleanup. Sleeps
+  and capture timeouts are clipped to the remaining budget; a failed capture
+  or exhausted budget ends settling and proceeds to the single Enter. After
+  Enter, at most two read-only looks share a separate 1-second observation
+  budget. These deadlines do not bound the original paste/key commands, buffer
+  cleanup or OS scheduling. They authorize no further keys.
+
+  Successful terminal commands return `submitted: true` and `verified`, with
+  no `reason`. `verified: true` means only that the bounded display comparison
+  saw a changed look; `false` means unchanged, unreadable or exhausted
+  observation. The comparison retains its whitespace and resize/reflow
+  handling. Display movement can be unrelated output, a spinner or a dialog;
+  an unchanged display is not proof that no effects occurred or that a draft
+  is pending. **Neither value authorizes retry or proves model acceptance.**
+
+  A failed paste or key command remains `E_SESSION_INPUT_FAILED`; an
+  observational failure does not turn successful terminal operations into a
+  refusal. Command errors may themselves be uncertain after partial effects.
+  This transport offers no exactly-once guarantee and does not guarantee that
+  a busy pane accepts the input. Wake schedules retain their existing rule:
+  any nonthrowing input answer is recorded as delivered, meaning terminal
+  operations, not model processing. Broker delivery/ack policy and harness
+  acceptance evidence remain separate contracts.
 - **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.

package/docs/implementation.md

@@ -65,11 +65,54 @@ published to npm. Its developer docs are in
 | `harness-trust.mjs` | reading (never writing) Claude's and Codex's folder trust for a launch |
 
 The schedule registry stores explicit concurrency caps, leaving the schedule
-cap absent for its effective default of five. Reads migrate legacy stored one
-to absent once, under `registry.lock`, and record `capsVersion: 2`. Registration
-and cap updates use that same short lock; later explicit one stays explicit.
-`readRegistry()` returns stored choices; scheduling and status apply the default
-without writing it back. The trigger cap is independent and absent means no cap.
+cap absent for its effective default of five. `readRegistry()` is a pure,
+bounded atomic-file snapshot: it takes no lock and writes nothing, projecting
+legacy implicit one to absent and `capsVersion: 2` only in memory. Its no-follow
+regular-file descriptor accepts an atomic rename between stat and open, so it
+returns a complete old or new snapshot; other bounded readers retain their
+identity check. Invalid present schedule or trigger caps are refused.
+Registration, unregistration and cap updates reread under `registry.lock` and
+compare against the raw snapshot, so even unchanged membership persists the
+migration. A successful write removing legacy one emits a stderr notice naming
+the one-slot restoration command. `writeRegistry()` remains a raw atomic writer;
+read-modify-write callers must supply the lock and reread. Later explicit one
+stays explicit, including one reintroduced by an older writer: the stored
+marker cannot distinguish its provenance. The trigger cap stays independent.
+
+The shared mkdir lock retries every occupied-directory window within the
+caller's retry deadline, including owner-file publication and removal. It never
+removes a contender's lock or steals from a live, dead or unreadable owner;
+persistent contention ends in the caller's existing busy error.
+
+Spawn compensation returns its diagnostic and a structural uncertainty flag;
+only an incomplete result marks the original error's `details.unconfirmed`.
+CLI wrappers preserve that field, and the operation runner promotes a provider's
+literal true marker while retaining the nested envelope. Message-based consumers
+remain during the additive producer migration; do not replace stage evidence
+with a substring check or infer uncertainty from a retained home alone.
+
+The schedule child supervisor installs SIGINT/SIGTERM/SIGHUP handlers before
+launch and removes them on settlement. All catchable shutdown signals share
+its idempotent TERM/KILL path; the first stop cause is retained. The private
+receipt records interruption independently of both the first stop cause and
+the direct child's observed exit, so a signal during overflow cleanup still
+keeps an otherwise valid envelope unconfirmed. Group probes
+start at leader exit; an observed-empty group is permanently excluded from
+later probes/signals. Polling cannot eliminate the gap before observation or
+prove away PID reuse. Escaped sessions are outside the owned group, and
+SIGKILL/OOM or unrecoverable supervisor death cannot be cleaned up by handlers;
+a missing receipt supplies no child-exit evidence and cannot release a slot.
+
+Session input keeps terminal operations separate from display observation.
+The pre-Enter budget starts at paste completion, before best-effort buffer
+cleanup; post-Enter observation starts after the single key command returns.
+Both use a monotonic clock, clip sleeps and read-only capture subprocess
+budgets, and stop observing on failure or exhaustion. Capture subprocesses use
+SIGKILL on timeout so an ignored TERM cannot extend a probe; terminal command
+timeouts/errors are unchanged. Screen comparison can set only the observational
+`verified` boolean, never send another key or report terminal failure. Tests
+use inert command runners and clocks; they do not qualify broker delivery or
+harness acceptance.
 
 The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
 a provider. Provider behaviour lives in capabilities; the kernel supplies
@@ -241,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
@@ -273,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/oats-local.schema.json

@@ -99,7 +99,7 @@
         "disabled": {
           "description": "Workspace schedules this host does not run, by qualified id <member>/<id>, without a commit (`oats schedule disable <member>/<id>` writes it). Local schedules are enabled and disabled in oats-schedules.json.",
           "type": "array", "uniqueItems": true,
-          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" }
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,100}$" }
         }
       }
     },
@@ -111,7 +111,7 @@
           "description": "The workspace triggers and schedules this host agrees to run, by qualified id <member>/<id>, or \"*\" for every one the workspace places on this host (0.30). A workspace automation runs only when its runsOn is host.name, its owner is this host's gh account AND trust admits it; absent or empty, none runs. A host fact: the committed workspace file refuses it. Local triggers and schedules need no trust.",
           "oneOf": [
             { "const": "*" },
-            { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" } }
+            { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,100}$" } }
           ]
         }
       }

package/docs/official-catalog.md

@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
 
 | package | release | capabilities | package souls |
 |---|---|---|---|
-| `oats.framework` | `oats-framework/v1.6.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `oats.framework` | `oats-framework/v1.6.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
 | `oats.aweb` | `v1.21.1` | `oats.aweb` (messaging) | |
 | `oats.engineering` | `v1.8.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |

package/docs/packages.md

@@ -51,7 +51,7 @@ packages:
 - **Bare version** (`v4.1.1`, `4.1.1`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v4.1.1` or `oats-framework/v1.6.0`) and the payload path. An id
+  convention (`v4.1.1` or `oats-framework/v1.6.1`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.6.0
+  oats.framework: v1.6.1
   oats.okf: v4.1.1
   oats.aweb: v1.21.1
 teams:
@@ -333,11 +333,11 @@ A soul that names one of the package's capabilities with
   "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.6.0", "path": "oats-package" }
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.6.1", "path": "oats-package" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.6.0`
-resolves to tag `oats-framework/v1.6.0`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.6.1`
+resolves to tag `oats-framework/v1.6.1`. Resolving through the catalog never
 advances a lock by itself: `oats sync` does, and says so.

package/docs/release-lane.md

@@ -47,8 +47,8 @@ override; report the risk you accepted). It never touches the checkout it
 runs from: it exports the SHA into a detached worktree under the system
 temporary directory (recorded in `MANIFEST.json`, `--export <dir>` overrides)
 and runs every build step there. The bumped manifests exist only in that
-export; the version-bump commit to `main` remains the workflow's job, or a
-manual PR.
+export; the version-bump commit reaches `main` through the pull request the
+workflow opens (or a manual one), merged by a maintainer.
 
 `publish-npm` and `release-github` print their plan and refuse without
 `--yes`. `tag` creates the local tag without `--yes` but pushes only with
@@ -117,8 +117,12 @@ Everything after `build` reads `MANIFEST.json` and the files already staged:
   runs `release.yml`, whose steps are idempotent: it skips the live npm
   versions, re-uploads the same assets, and attaches the attestations. That
   later pass is the way to add provenance; nothing is republished.
-- **The version-bump PR.** The workflow's final step; open it by hand if the
-  workflow does not run.
+- **The version-bump PR.** The workflow's final step opens it and stops: the
+  run never merges into `main`. A maintainer reviews that the diff is the
+  version lines only and merges it. The PR is opened with the workflow token,
+  so no checks run on it by themselves; close and reopen it to run them, and
+  do not read missing checks as green. Open the PR by hand if the workflow
+  does not run.
 - **Legs for hosts you do not have.** The Linux AppImage/DEB need a Linux
   host; the lane says so and `stage` lists what is missing.