@awebai/oats 0.41.0 → 0.42.0

package/docs/execution-targets.md

@@ -134,33 +134,183 @@ options and environment, are left exactly as they were.
 #### 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
+global environment. A pane gets its session's environment over that (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.
+session, and anything set on the session with `set-environment -t`), plus
+what the launch command sets (`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, the
+capabilities' and the launch configuration's variables). **A pane's
+environment is its session's, `PATH` included, whoever creates its window**:
+an instance, the Desktop or an operator's shell. The tmux client that creates
+the window (or respawns the pane, in a restart in place) runs with only
+`LANG`, `LC_ALL` and `LC_CTYPE`, and tmux takes a client's `PATH` only when
+the client has one. The launch command then puts the home's own `oats` shim
+first. So:
+
+- A pane's `PATH` is its session's `PATH` when the session has one, otherwise
+  the server's global `PATH`. It no longer follows the process that runs each
+  spawn or start (it did before 0.42.0).
+- A `PATH` and the variables that interpret it (a version manager's
+  bookkeeping, such as mise's `__MISE_DIFF`, or nvm's) therefore come from
+  one environment. OATS no longer overlays a creator's `PATH` onto another
+  environment's companion state. It does not make an existing or external
+  server's environment, a session override or a launch configuration's
+  `PATH` coherent: it uses them as they are.
 - 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.
 
+**The harness is looked up where its pane looks it up.** A launch whose
+executable is a bare name (the harness's own, or a launch configuration's
+`executable` without a `/`) looks it up on the `PATH` the pane will run it
+with, by this precedence:
+
+1. a declared absolute `executable` is used as it is, with no lookup (a
+   relative one is resolved against the deployment directory, as before);
+2. a `PATH` set in the launch configuration's `env` (a literal, or a
+   `fromEnv` reference resolved on this host) is what the pane's command
+   line applies, so the lookup uses it;
+3. otherwise the session's or the server's `PATH`, read with the strict
+   reader below.
+
+The lookup happens twice. Before anything is created, against the `PATH` the
+pane is expected to have: for a start that reuses the home's recorded pane
+(running, or left as a shell), that pane's own session on its recorded
+server, whatever the OATS server holds and whether one runs; otherwise the
+session's or the server's when the server runs, otherwise the `PATH` of the
+environment the server is created with. And again
+on the session OATS actually gets, whoever created it and with whatever
+environment (another creator that won the race to create the server, a
+session whose environment overrides `PATH`): found elsewhere, the launch runs
+and records that executable; not there, the spawn is refused and rolled back
+as any failed launch is, and a start is refused before it launches anything.
+For a start the first check comes before a restart stops its harness; the
+second, on the session OATS gets, comes after that session (and, when none
+ran, the server) was created, and for a restart whose window went away
+during its stop, after that stop. A session a refused start created is left
+in place. A start under a new selection with no server running reads the
+environment the server will be created with (your login environment, or its
+fallback, below) for its first check, never this process's `PATH`. A recorded executable (a start that reuses the home's launch) is
+kept as it is: it then runs with its pane's environment, but it is not looked
+up again. A `--no-launch` spawn, and a preview with no server running, look
+the harness up on the process's own `PATH`, as before.
+
+A session's `PATH` can be in four states, and the lookup tells them apart:
+no entry (the server's `PATH` is used), a value, even an empty one (used as
+it is), an explicit clear (`unset PATH;` in `show-environment -s`: tmux gives
+the pane no `PATH` at all), or a value the strict reader leaves out. The last
+two, and a server with no `PATH` or one that cannot be read, are refused: OATS
+never substitutes the server's `PATH`, the caller's or a default for them.
+
+A harness that is not on that `PATH` is refused with `E_HARNESS_UNAVAILABLE`
+(a configuration's declared bare name with `E_LAUNCH_EXECUTABLE`). The message
+names where it looked (`the PATH of tmux session <name>`, `the global PATH of
+the OATS tmux server (<socket>)`, or the launch configuration's) and the
+remedies: declare the executable's absolute path in the launch configuration,
+set `PATH` in the launch configuration, or start the server from your own
+shell. It never prints a `PATH`'s contents.
+
 Who starts the `oats` server, after an install, a reboot or its last session
-ending, decides that ambient environment:
+ending, decides that ambient environment.
+
+**When OATS starts the server, it gives it your login environment.** The
+`new-session` that creates an agents' session is the only OATS call that
+starts the server. When no server answered before it, whoever runs it (a spawn
+or a start from an instance, the Desktop, an operator's shell, a schedule
+runner or a trigger), OATS reads the environment your own login shell sets up
+and starts the server with that:
+
+- **Only in your own session.** The login shell is run only for a process
+  whose `HOME` is your home directory in the password database. A process
+  that set another `HOME` (a sandbox, a test fixture, an account switch that
+  kept the caller's environment) is not taken to run in your login session:
+  its reading fails and the fallback below applies.
+- **The shell** is your login shell from the password database (not the
+  creator's `SHELL`): bash, zsh or fish, run as `-l -i -c` from your home
+  directory, so your profile and rc files run as they do in a terminal (a
+  version manager's activation, an agent socket an rc exports).
+- **It starts from a fixed seed**, nothing else of the creator: `HOME`,
+  `USER`, `LOGNAME` and `SHELL` from the password database, `PATH` as
+  `/usr/bin:/bin:/usr/sbin:/sbin`, `TERM=dumb`, the creator's `LANG`,
+  `LC_ALL` and `LC_CTYPE`, and the session variables `SSH_AUTH_SOCK`,
+  `DISPLAY`, `WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR` and
+  `DBUS_SESSION_BUS_ADDRESS`. Each of those comes from the first source that
+  has it, an empty value counting as present: the creator, when it is not an
+  instance; for an instance, the global environment of the server its home
+  records; then your user session, read as data (`systemctl --user
+  show-environment` on Linux, decoding systemd's `$'…'` values; `launchctl
+  getenv` on macOS). A user session that cannot be read leaves those names to
+  your login shell, and OATS says so on stderr, without values. On macOS the
+  agent socket launchd gives the apps and terminals you open is not a
+  `launchctl` variable (it is the `SSH_AUTH_SOCK` key of the
+  `com.openssh.ssh-agent` job), so `launchctl getenv` usually has none: a
+  server OATS starts there has your agent socket when the process that starts
+  it has one (the Desktop opened from the Finder or the Dock, a terminal), or
+  when your login shell sets it. The tool runs
+  from `/usr/bin:/bin:/usr/sbin:/sbin` with your own `HOME`, `USER`,
+  `LOGNAME` and, on Linux, your runtime directory (`/run/user/<uid>`), never
+  with the creator's environment. No `OATS_`,
+  `AWEB_`, harness or credential variable of the creator is in the seed.
+- **What your setup produces wins**: the shell's answer is final, including
+  what its rc files set, except the functions bash exports
+  (`BASH_FUNC_<name>%%`, from a profile's `export -f`): they are code every
+  bash in a pane would import, and OATS drops them. OATS then removes the
+  kernel's names and the instance-identity names, as below, and keeps your
+  OATS configuration as the creator has it: every `OATS_` and `PI_AGENTS_`
+  variable that is not a kernel name (`OATS_HOME_DIR`, `OATS_TMUX_SESSION`,
+  `OATS_PACKAGE_CATALOG`, …) is the creator's, over what your rc files set;
+  for an instance, the one the server its home records has, never its own. The server is still reached with the
+  creator's `TMUX_TMPDIR`.
+- **The answer is one frame on the shell's stdout**: a small emitter run by
+  the shell writes the environment as JSON between a start and an end
+  delimiter that carry a random value made for this reading only. Exactly one
+  complete frame of that reading, start before end, is the answer; anything
+  else the shell prints (a banner, a prompt, text that looks like an
+  assignment, like JSON or like a frame of another reading) is discarded, and
+  a missing, cut, repeated or misordered frame is no answer. The shell's
+  errors are not read, and no value is written to a file, an argument or a
+  log. It is accepted only whole: exit status 0, at most 1 MiB for all the
+  shell printed, one JSON object whose values are all text, plain
+  identifiers as names, `HOME` and `PATH` present. Nothing in it is
+  evaluated. Not a descriptor of its own: bash 5.3, started `-l -i`, marks
+  the descriptors it inherits from 3 to 19 close-on-exec, so an answer there
+  never reaches the emitter. The random value keeps accidental output apart;
+  it does not guard against your own start-up files, which can also send the
+  shell's stdout elsewhere (then there is no answer, and the fallback
+  below applies).
+- **It is bounded at 5 s.** The shell runs in its own process group; at the
+  deadline that group, and only it, is killed, and the read ends even when a
+  descendant still holds the shell's stdout. A descendant that put itself in its own
+  session or group (a daemon an rc starts) is outside that group, and OATS
+  does not promise to end it.
+- **When it cannot be read** (a process whose `HOME` is not yours, a timeout, a non-zero exit, a partial,
+  oversized or malformed answer, no `HOME` or `PATH`, a shell that is not
+  bash, zsh or fish or cannot run), OATS prints one line on stderr saying
+  why and what it used instead, never a value, and `--json` output stays one
+  valid envelope. A creator outside every instance falls back to its own
+  environment without the kernel's names (the behaviour before 0.42.0); an
+  instance falls back to a copy of the server its home records, as below, or
+  is refused, never to its own environment. A fallback is degraded: it is
+  neither a login environment nor proof of a working agent socket, and it
+  passes on whatever the creator's environment holds. A creator whose `PATH`
+  names a version manager's directories without the variables that interpret
+  them (a process started by a service manager, an agent's shell) gives the
+  server that same mismatch, and a version-manager wrapper can then resolve
+  its own name again and loop, as in #616. OATS prevents that only when it
+  reads your login environment.
+
+A server OATS did not start keeps what its starter gave it:
 
 | 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 |
+| OATS (any creator; see above) | your login environment, or the creator's fallback |
+| you, from your own shell (`tmux -L oats new-session …`) | that shell's |
+| a service manager (`systemd-run`, a unit, launchd) | only that manager's environment |
 
+OATS uses an existing server as it is and does not certify its environment.
 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.
+moment, tmux starts one server and nothing says which of the two it is. A
+server that exits between OATS's lookup and its `new-session` is started as
+any server OATS starts: with your login environment, or its fallback.
 
 **What OATS removes, for every creator.** The names the kernel itself sets
 never go into the environment OATS creates an agents' session or window
@@ -174,13 +324,16 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
 `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_TRIGGER_EVENT_FILE`, `OATS_TEST_LOGIN_SHELL` (a test seam that replaces
+the login shell, honoured only for a process whose `HOME` is not your home
+directory; a launch configuration cannot set it), `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
+`OATS_TMUX_SESSION`) are yours and stay, also when OATS starts the server
+with your login environment (above). An agent's plain `oats` finds its
 deployment from its home.
 
 **An instance creates an agents' session or window without its own
@@ -193,7 +346,8 @@ 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
+- When such a process has to create the tmux session on a server that runs,
+  or its login environment could not be read, 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
@@ -218,20 +372,19 @@ that triggered it), and `oats schedule run-now` typed inside an instance.
   `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.
+  creates it runs with `LANG`, `LC_ALL` and `LC_CTYPE` only, which that client
+  needs to start on a host whose only UTF-8 locale is the one they name, as
+  every creator's does. tmux hands a pane none of them: the pane, the session
+  and the server keep the values they had, and the pane's `PATH` is the
+  session's or the server's. Nothing of the instance travels, its `PATH`
+  included. 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
+  on the `oats` server, its login environment is not what the server gets
+  (the server runs, or the login environment could not be read), 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`,
@@ -277,42 +430,46 @@ that triggered it), and `oats schedule run-now` typed inside an instance.
   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:
+  path, as is every window client (it has no `PATH` to look one up with). 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
+  process whose `PATH` is not set has no tmux to run by its full path: it
+  cannot create a session, nor open or respawn a window (the window is
+  refused). Only finding a session that is already there 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.
+other creator: when it starts the server, your login environment (above);
+otherwise, and as the fallback, its environment without the names above.
 
 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 new-session -d -s <session> -n hq   # start it yourself: it keeps your shell's environment
 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.
+- There is no manual step: when OATS starts the server, it gives it your
+  login environment. A server you start yourself keeps your shell's
+  environment, and one a service manager starts gets only that manager's.
+  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.
+  and panes that already run keep the environment they have. Windows created
+  from now on take it, `PATH` included (with no session override of it), and
+  their harness is looked up on that `PATH`.
 - `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.
+  host. The next start gives the new server your login environment when OATS
+  starts it, or the environment of whoever else does.
 - `-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> …`.

package/docs/implementation.md

@@ -60,7 +60,9 @@ published to npm. Its developer docs are in
 | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
 | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
 | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
-| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation, the hook environment rules, the readiness wire |
+| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
+| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`), the hook environment rules, the readiness wire |
+| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
 | `servers.mjs` | routing commands to a registered server |
 | `harness-trust.mjs` | reading (never writing) Claude's and Codex's folder trust for a launch |
 

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

@@ -0,0 +1,7 @@
+# OATS 0.41.1
+
+## Changed
+
+- **OATS Desktop opens up to 200 terminals.** Desktop allowed 20 open terminals
+  across all its windows, and with many instances it refused the next one with
+  "Terminal limit reached. Close a terminal first." The limit is now 200.