@awebai/oats 0.68.1 → 0.69.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/bin/oats.mjs +102 -22
  2. package/docs/capabilities.md +49 -5
  3. package/docs/configuration.md +68 -2
  4. package/docs/desktop-cli-api.md +355 -12
  5. package/docs/desktop-instance-start.md +88 -3
  6. package/docs/desktop.md +108 -10
  7. package/docs/execution-targets.md +514 -62
  8. package/docs/harness-trust.md +3 -1
  9. package/docs/implementation.md +28 -11
  10. package/docs/integrations.md +1 -1
  11. package/docs/oats-local.schema.json +2 -2
  12. package/docs/official-catalog.md +4 -3
  13. package/docs/packages.md +7 -7
  14. package/docs/release-notes/v0.69.0.md +658 -0
  15. package/docs/release-notes/v0.69.1.md +25 -0
  16. package/docs/servers.md +44 -5
  17. package/docs/souls-and-instances.md +11 -7
  18. package/docs/tui.md +77 -12
  19. package/docs/upgrading.md +12 -7
  20. package/docs/workspaces.md +1 -1
  21. package/lib/core.mjs +345 -89
  22. package/lib/file-pieces.mjs +49 -0
  23. package/lib/instance-events.mjs +25 -4
  24. package/lib/launch-prompt-fixtures/README.md +62 -0
  25. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  26. package/lib/launch-prompt-fixtures.mjs +49 -0
  27. package/lib/launch-prompt-resume.mjs +55 -0
  28. package/lib/login-environment.mjs +27 -9
  29. package/lib/schedule.mjs +3 -3
  30. package/lib/servers.mjs +117 -23
  31. package/lib/session-end.mjs +82 -0
  32. package/lib/session-input.mjs +43 -9
  33. package/lib/session-resume-contract.mjs +32 -0
  34. package/lib/session-resume.mjs +310 -0
  35. package/lib/session-seen.mjs +163 -0
  36. package/lib/session-viewer.mjs +147 -44
  37. package/lib/soul-composition.mjs +2 -1
  38. package/lib/start-env.mjs +110 -0
  39. package/lib/tmux-server-scope.mjs +139 -14
  40. package/lib/workspace.mjs +38 -4
  41. package/package-catalog.json +10 -4
  42. package/package.json +1 -1
  43. package/packages/client/cli-adapter.mjs +9 -0
  44. package/packages/client/cli-locator.mjs +3 -2
  45. package/packages/client/deployment-data.mjs +7 -0
  46. package/packages/client/deployment-panel.mjs +3 -0
  47. package/packages/client/file-output-exec.mjs +98 -0
  48. package/packages/client/launch-prompt-outcome.mjs +25 -13
  49. package/packages/client/own-codes.mjs +2 -0
  50. package/packages/client/session-attach.mjs +35 -5
  51. package/packages/client/session-resume-cli.mjs +64 -0
  52. package/packages/client/session-resume-trigger.mjs +167 -0
  53. package/packages/client/session-resume.mjs +332 -0
  54. package/packages/client/tmux-status.mjs +30 -7
  55. package/packages/client/waiting-on-you.mjs +11 -4
  56. package/packages/client/workspace-step.mjs +17 -5
  57. package/packages/record/lib/last-conversation.mjs +123 -0
  58. package/packages/record/lib/session-roots.mjs +10 -1
  59. package/packages/tui/lib/client.mjs +1 -1
  60. package/packages/tui/lib/main.mjs +5 -3
  61. package/packages/tui/lib/model.mjs +45 -12
  62. package/packages/tui/lib/store.mjs +8 -7
  63. package/packages/tui/lib/term/text.mjs +12 -9
  64. package/packages/tui/lib/views/frame.mjs +72 -7
  65. package/packages/tui/lib/views/help.mjs +8 -3
  66. package/packages/tui/lib/views/instances.mjs +3 -2
  67. package/skills/oats-getting-started/SKILL.md +117 -4
@@ -58,8 +58,17 @@ exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
58
58
  a retained dead pane also reads `false`. A wrapper shell with a live non-shell
59
59
  descendant still reads `true`. Status shares session inspection's pane rule,
60
60
  with one batched pane read per socket/session and one lazy process scan across
61
- all panes that need it. A recorded server or pane that cannot be read gives
62
- `running: null` with `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
61
+ all panes that need it. It reads the agent's pane alone, so a window with
62
+ another pane reads as one without it
63
+ ([which pane is the agent's](#which-pane-is-the-agents)). A recorded server or
64
+ pane that cannot be read gives `running: null` with `runtimeState:
65
+ "unreachable"`, and so do a window where OATS cannot tell which pane is the
66
+ agent's and a session that holds two windows of the instance's name, each
67
+ with its reason as `runtimeError`. A local status read (0.69)
68
+ also records, in a kernel-private file of this machine beside the resume
69
+ sweep's per-boot note, what it saw of each home, for the sweep alone; it
70
+ never changes the answer, and a status routed with `--server` records nothing
71
+ here ([Which losses come back](#which-losses-come-back)). The environment variables are read when the spawn runs, and `oats
63
72
  inspect --json` reports the session a new spawn would open in as `session`
64
73
  (`{tmuxSession}`). A spawn refuses an instance name that is a live window in the
65
74
  session it would open in, on the OATS tmux server (`E_INSTANCE_NAME_TAKEN`); a
@@ -69,6 +78,47 @@ commands target each home's exact recorded window, so the two never mix. The
69
78
  receipt records the session, window and socket. The spawn result prints the
70
79
  attach command.
71
80
 
81
+ <a id="which-pane-is-the-agents"></a>
82
+ #### Which pane is the agent's
83
+
84
+ An agent's window can hold more than one pane: a person or a tool can split
85
+ it, as oats.setup's no-echo prompt does. Status and every session command act
86
+ on one pane of the window, the agent's.
87
+
88
+ - **The mark.** Whenever OATS creates or respawns the agent's pane (a spawn's
89
+ window, a start's or restart's new window, a restart in place), it sets the
90
+ tmux pane option `@oats-agent` on it, its value the instance name, which is
91
+ the window's name. It is set in the launch's own tmux call, and a mark that
92
+ cannot be set does not fail the launch. Pane options exist from tmux 3.0.
93
+ The mark is internal: it is what OATS sets, not an interface for other
94
+ tools.
95
+ - **The rule.** In a window with one pane, that pane is the agent's, marked or
96
+ not. With several, it is the pane marked with the instance's name; when
97
+ none is, the unmarked pane with the lowest pane id (`%N`, tmux's creation
98
+ order: the window's own pane comes before any split of it). A pane marked
99
+ with another instance's name is never the agent's.
100
+ - **A window launched by an earlier kernel** has no mark: it resolves to its
101
+ lowest pane id until the next start or restart marks it.
102
+ - **When OATS cannot tell** (two or more panes marked with the instance's
103
+ name, or several panes and none unmarked or marked with it), status reads
104
+ `running: null` with `runtimeState: "unreachable"` and one of these
105
+ sentences as `runtimeError`, and `session inspect`, `session input` (wakes
106
+ included), `session attach`, stop and restart refuse with the same sentence:
107
+
108
+ ```text
109
+ the window has 2 panes marked as <name>'s agent pane (%3, %7); close all but the agent's with tmux kill-pane -t <id>, or close the window and start the instance
110
+ the window has 2 panes and none is <name>'s agent pane (%2, %7); close the panes that aren't, or close the window and start the instance
111
+ ```
112
+
113
+ - **Everything else is the agent's pane alone.** The fallback-shell,
114
+ dead-pane and descendant rule judges it alone, and a `paneId` in an answer
115
+ is its id; the
116
+ other panes never make the instance unknown. Input and wakes paste into it
117
+ even when the person's focus is in another pane. Stop signals only the
118
+ processes under it, and a restart in place respawns it and marks it. The
119
+ size inspect reports stays the window's. The viewer shows the whole window
120
+ ([attach](#inspect-input-and-attach)).
121
+
72
122
  <a id="the-oats-tmux-server"></a>
73
123
  #### The OATS tmux server
74
124
 
@@ -137,14 +187,22 @@ options and environment, are left exactly as they were.
137
187
  earlier kernel failed a start whose recorded tmux server could not be
138
188
  reached when a sizing command was refused; this one does not.
139
189
 
140
- #### A server started from inside a systemd service
190
+ <a id="a-server-started-from-inside-a-systemd-service"></a>
191
+ #### Where sessions run: the server's scope and each agent's
141
192
 
142
- A tmux server lives in the cgroup of the process that started it. When that
143
- process runs inside a systemd service, the server and every agent pane in it
144
- end when the service stops. The schedule tick's oneshot service ends after
145
- each tick, and a Desktop run as a user service restarts at each upgrade. So,
146
- on Linux, when OATS starts the `oats` server (no server answered) from inside
147
- a service, it starts it in a transient scope of its own:
193
+ A tmux server lives in the cgroup of the process that started it, and its
194
+ panes with it. On a systemd host that cgroup can end, and take every agent
195
+ with it: a service's cgroup ends when the service stops (the schedule tick's
196
+ oneshot service ends after each tick, a Desktop run as a user service restarts
197
+ at each upgrade), and systemd-oomd, under memory pressure, kills a whole cgroup
198
+ of the user manager's: a client application's `app-*.scope` (OATS Desktop or
199
+ `oats tui` launched from a desktop session) with everything started from it.
200
+ So, on Linux, on the unified cgroup hierarchy, OATS keeps the server out of
201
+ its creator's unit, and each agent's harness out of the server's cgroup.
202
+
203
+ **The server.** When OATS starts the `oats` server (no server answered) from
204
+ inside a unit of the user manager, or from a system service, it starts it in
205
+ a transient scope of its own:
148
206
 
149
207
  ```text
150
208
  systemd-run --user --scope --collect --quiet --unit oats-tmux-<hash>-<random> -- env -u INVOCATION_ID tmux -u -L oats new-session -d …
@@ -161,25 +219,29 @@ systemd-run --user --scope --collect --quiet --unit oats-tmux-<hash>-<random> --
161
219
  of the SHA-256 of the server's address, and `<random>` 8 random hex digits.
162
220
  `systemd-run` and `env` are the system's own (`/usr/bin`, `/bin`), never
163
221
  ones found on `PATH`.
164
- - **The server outlives the service.** It is a sibling of the service, not
165
- part of it: the service can end, stop or restart, and the server and its
166
- agents go on. The scope ends when its last process does, and `--collect`
167
- removes it then. That is usually the server. On a tmux without systemd
168
- support the panes are in the scope too, so a process that outlives the
169
- server (one an agent started in the background) keeps the scope until it
170
- exits. On a tmux with systemd support each pane has a scope of its own,
171
- but the dead server's scope still stays listed (`loaded inactive dead`)
172
- while a process from one of its panes lives. Either way, a later start
173
- never reuses that scope: it gets one of its own.
174
- - **See it:** `systemctl --user status 'oats-tmux-<hash>-*.scope'` (or
175
- `'oats-tmux-*.scope'` for every OATS server), or
176
- `systemd-cgls --user`. A tmux built with systemd support also puts each
177
- pane in a `tmux-spawn-<id>.scope` of its own.
178
- - **When the creator is inside a service:** `/proc/self/cgroup` is the
179
- unified hierarchy (one `0::<path>` line) and the path's last component ends
180
- in `.service`. An operator's shell (`session-N.scope`), an agent's pane, and
181
- macOS are not, and start the server as before. A server that already
182
- answers is used as it is.
222
+ - **The server outlives its creator's unit.** It is a sibling of that unit,
223
+ not part of it: the service can end, stop or restart, and the client can
224
+ quit or be killed, and the server and its agents go on. The scope ends when
225
+ its last process does, and `--collect` removes it then. That is usually the
226
+ server. On a tmux without systemd support the panes are in the scope too
227
+ (each agent's harness is not: below), so a process that outlives the server
228
+ (one an agent's shell started in the background) keeps the scope until it
229
+ exits. On a tmux with systemd support each pane has a scope of its own, but
230
+ the dead server's scope still stays listed (`loaded inactive dead`) while a
231
+ process from one of its panes lives. Either way, a later start never reuses
232
+ that scope: it gets one of its own.
233
+ - **When the creator is inside a unit:** `/proc/self/cgroup` is the unified
234
+ hierarchy (one `0::<path>` line), and the path's last component ends in
235
+ `.service` (any service, system or user), or ends in `.scope` and the path
236
+ runs through the user manager (`…/user@<uid>.service/…`): a desktop
237
+ application's `app-*.scope`, a terminal's `vte-spawn-*.scope`, an agent's
238
+ own `oats-agent-*.scope` (an agent that spawns), the manager's `init.scope`.
239
+ A login session's scope (`/user.slice/user-<uid>.slice/session-N.scope`, an
240
+ ssh or tty login) sits beside the user manager, not in it, and starts the
241
+ server as before, as macOS does. So does a Linux host not booted with
242
+ systemd (a container's own init, another init system): its cgroup paths
243
+ name no unit of a user manager. A server that already answers is used as
244
+ it is: one started before this rule keeps the cgroup it has.
183
245
  - **The limits.**
184
246
  - Only the unified cgroup hierarchy is judged. On the old or hybrid
185
247
  hierarchy the server starts as before. When `INVOCATION_ID` shows the
@@ -187,9 +249,9 @@ systemd-run --user --scope --collect --quiet --unit oats-tmux-<hash>-<random> --
187
249
  that service.
188
250
  - The scope needs the user's systemd manager and its bus
189
251
  (`XDG_RUNTIME_DIR`), and `systemd-run` and `env` in `/usr/bin` or `/bin`:
190
- a host without them gets the warning below at every start from a
191
- service. A system service (one outside the user's manager) is
192
- wrapped the same way, and without a user bus it gets the warning below.
252
+ a host without them gets the warning below at every start from a unit.
253
+ A system service (one outside the user's manager) is wrapped the same
254
+ way, and without a user bus it gets the warning below.
193
255
  - When `systemd-run` is missing or fails, and no other creator's server
194
256
  answers in the meantime, the server starts as before. The answer's
195
257
  `warnings` (spawn, session start and restart), and the schedule tick's
@@ -199,6 +261,57 @@ systemd-run --user --scope --collect --quiet --unit oats-tmux-<hash>-<random> --
199
261
  - macOS is not wrapped: launchd lets the server, which leaves the job's
200
262
  process group, outlive the job.
201
263
 
264
+ **Each agent's harness.** Every launch of a harness (spawn, session start and
265
+ restart, and so a resume) runs it in a transient scope of its own, in the
266
+ user manager's default slice, wherever the server is:
267
+
268
+ ```text
269
+ … PATH=<home>/.oats/bin:… systemd-run --user --scope --collect --quiet --unit oats-agent-<hash>-<random> -- env -u INVOCATION_ID /bin/sh -c '<record the start> && exec <harness> …'
270
+ ```
271
+
272
+ - **One agent per kill.** systemd-oomd ends one cgroup at a time: with a scope
273
+ per agent, memory pressure that selects an agent ends that agent, never the
274
+ server or the other agents. `<hash>` is the first 12 hex digits of the
275
+ SHA-256 of the home's canonical path, and `<random>` 8 random hex digits
276
+ per launch: a scope ends with its last process, so a later launch never
277
+ reuses its name. `systemd-run` and `env` are the system's own.
278
+ - **Nothing else changes.** Each step execs the next, so the harness keeps the
279
+ process `systemd-run` began as: it is the pane's direct child, its exit
280
+ status is the pane shell's, and stop, status and the launch-prompt check see
281
+ the pane as without the scope. `INVOCATION_ID` is removed as for the server.
282
+ The scope is decided at each launch and is never recorded: the home's
283
+ `command`, its launch recipe, the start's receipt and the retirement baseline
284
+ are as before, and `oats spawn --preview` does not show it.
285
+ - **The conditions.** Linux booted with systemd (`/run/systemd/system` is a
286
+ directory, as `sd_booted` reads it), and the launching process on the
287
+ unified cgroup hierarchy, whatever unit it is in. Before it wraps, the launch checks that a
288
+ scope can be created: it runs `systemd-run --user --scope --collect --quiet
289
+ -- true` with the pane's own `XDG_RUNTIME_DIR` and
290
+ `DBUS_SESSION_BUS_ADDRESS`: what the launch's command sets (a launch
291
+ configuration or a capability), else the session's, else the server's. It
292
+ is bounded to 5 seconds. One OATS command
293
+ checks once for each `systemd-run` and pair of values, so a start of many
294
+ agents checks once.
295
+ - **When it cannot.** On a systemd host, when the check fails, `systemd-run`,
296
+ `env` or `true` is not in `/usr/bin` or `/bin`, or the pane's environment
297
+ cannot be read, the harness is launched exactly as before, and the answer's
298
+ `warnings` (spawn, session start and restart), and a `launch-warning`
299
+ event once the launch is recorded (a launch refused after the check leaves
300
+ none), say once `the agent's harness runs in the OATS tmux server's cgroup,
301
+ not a scope of its own: <reason>`. The sweep (`oats session resume`) says
302
+ it once in its own `warnings`, not in each row. A pane whose server has no
303
+ `XDG_RUNTIME_DIR` or bus (a server started where none was set, a user
304
+ without lingering) fails the check. Off Linux, on a Linux host not booted
305
+ with systemd (a container's own init, another init system: no user manager
306
+ and no systemd-oomd), and on the old or hybrid hierarchy, nothing changes
307
+ and nothing is said.
308
+ - **What is left.** `systemd-run` could still fail between the check and the
309
+ pane. The pane's shell then reads exit status 1, an ordinary exit that is
310
+ never taken for a harness to bring back.
311
+ - **See it:** `systemctl --user status 'oats-agent-<hash>-*.scope'` (one home),
312
+ `systemctl --user list-units 'oats-agent-*'` (every agent), or
313
+ `systemd-cgls --user`.
314
+
202
315
  <a id="the-servers-start-environment"></a>
203
316
  #### The environment of the server and its panes
204
317
 
@@ -567,9 +680,9 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
567
680
  the login shell, honoured only for a process whose `HOME` is not your home
568
681
  directory; a launch configuration cannot set it),
569
682
  `OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS`, `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS`,
570
- `OATS_TEST_PROCESS_START_PS` (below), `OATS_TEST_CGROUP` and
571
- `OATS_TEST_SYSTEM_TOOL_DIRS` (test seams of the server's
572
- [own scope](#a-server-started-from-inside-a-systemd-service)), a `worktree` hook's tree
683
+ `OATS_TEST_PROCESS_START_PS` (below), `OATS_TEST_CGROUP`,
684
+ `OATS_TEST_SYSTEMD_BOOTED` and `OATS_TEST_SYSTEM_TOOL_DIRS` (test seams of the server's and the agents'
685
+ [own scopes](#where-sessions-run-the-servers-scope-and-each-agents)), a `worktree` hook's tree
573
686
  (`OATS_TREE`, `OATS_TREE_CLONE`, `OATS_TREE_REMOTE`, `OATS_TREE_MEMBER`,
574
687
  `OATS_TREE_BASE`, `OATS_TREE_BASE_OID`, `OATS_PURPOSE`, `OATS_TREE_ORIGIN`), `OATS_TEAM_NAME`, `OATS_TEAM_SCOPE`,
575
688
  `OATS_TEAM_ID`, `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS`, `OATS_TEAMS`,
@@ -656,7 +769,8 @@ that triggered it), and `oats schedule run-now` typed inside an instance.
656
769
  its receipt, a pending start). A launch hook that does not declare
657
770
  `launchPreview` has already run by then, and a warning it returned is
658
771
  already a `launch-warning` event of the home, as before any other late
659
- refusal of a start (`E_SESSION_RUNNING`, `E_LAUNCH_ENV_MISSING`). Nothing
772
+ refusal of a start (`E_SESSION_RUNNING`, `E_LAUNCH_ENV_MISSING`,
773
+ `E_LAUNCH_ENV_CHANGED`). Nothing
660
774
  undoes what that hook did, and there is nothing to clean up: a launch hook
661
775
  may do idempotent provider registration on a real start and no more
662
776
  ([capabilities.md](capabilities.md)), so the next start repeats it
@@ -828,6 +942,8 @@ saved route that records `herdrPath` still loads; the field is ignored.
828
942
  |---|---|
829
943
  | `oats spawn <soul> [--no-launch]` | Creates the home and launches the harness. `--no-launch` creates the home only. |
830
944
  | `oats session start --home <abs>` | Starts a stopped or never-launched instance again in its existing home. |
945
+ | `oats session start --resume --home <abs>` | Starts an instance whose session was lost again, in its own last conversation ([Resume after a shutdown](#resume-after-a-shutdown)). |
946
+ | `oats session resume [--deployment <dir>] [--plan]` | Resumes every lost session of this machine's deployments ([Resume after a shutdown](#resume-after-a-shutdown)). |
831
947
  | `oats session restart --home <abs>` | Stops the running harness and starts it again in place. |
832
948
  | `oats instance stop <instance> --plan` / `--apply` | Stops the harness and keeps home, work and launch recipe. |
833
949
  | `oats retire <instance>` | Ends the session and retires the instance ([souls-and-instances.md](souls-and-instances.md#retire)). |
@@ -845,7 +961,9 @@ included, opens on [the OATS tmux server](#the-oats-tmux-server).
845
961
  run every check before anything starts. `--model` replaces the recorded model
846
962
  for this and later starts.
847
963
  - A live harness is refused (`E_SESSION_RUNNING`). A fallback shell or a dead
848
- pane is reused in place. A missing window, or one whose tmux server cannot
964
+ pane is reused in place: the agent's pane is respawned and marked, and the
965
+ window's other panes are left as they are
966
+ ([which pane is the agent's](#which-pane-is-the-agents)). A missing window, or one whose tmux server cannot
849
967
  be reached, is created again on the OATS tmux server, and the start warns when that is
850
968
  not the server the home recorded ([Existing instances](#existing-instances)).
851
969
  A server whose socket file is missing counts as gone only when no process
@@ -855,7 +973,7 @@ included, opens on [the OATS tmux server](#the-oats-tmux-server).
855
973
  is refused (`E_INSTANCE_RETIRING`).
856
974
 
857
975
  `session restart` takes the same flags. It sends SIGTERM to the harness and
858
- its children, waits `--stop-grace <seconds>` (default 20, at most 300), then
976
+ its children, the processes under the agent's pane, waits `--stop-grace <seconds>` (default 20, at most 300), then
859
977
  starts in place. It never escalates: a harness still running is reported
860
978
  (`E_SESSION_STOP_FAILED`) and nothing is launched.
861
979
 
@@ -1023,7 +1141,8 @@ bounded authority. A prompt receipt does not assert receive readiness.
1023
1141
  children and uncommitted work, with a `planRevision`. `--apply --plan-revision
1024
1142
  <rev> --idempotency-key <key>` stops the instance and its recorded children
1025
1143
  first (`--no-recursive` stops only the instance), with the same bounded
1026
- SIGTERM. Restart the instance later with `oats session start` or
1144
+ SIGTERM, sent only to the processes under the agent's pane
1145
+ ([which pane is the agent's](#which-pane-is-the-agents)). Restart the instance later with `oats session start` or
1027
1146
  `oats session restart`. An instance whose recorded tmux socket file is
1028
1147
  missing while a process works in its home, or the process scan cannot run,
1029
1148
  is not reported idle: its result is `E_SESSION_UNAVAILABLE` and nothing is
@@ -1033,6 +1152,226 @@ that meets a retire of any of them answers `E_INSTANCE_RETIRING`, one that
1033
1152
  meets another stop `E_LIFECYCLE_BUSY`, before anything is stopped
1034
1153
  ([the table](desktop-cli-api.md#lifecycle-pairs)).
1035
1154
 
1155
+ **Stop an instance with OATS to keep it stopped** (Desktop's Stop, `oats
1156
+ instance stop`): the stop's record names the start it ended, and a resume
1157
+ never brings that start back. A stop of an instance that already reads
1158
+ `lost` signals nothing and records the stop all the same, so the instance
1159
+ stays stopped (on a full disk it cannot, and it stays `lost`). A tmux window
1160
+ killed by hand, or a harness killed by a signal, leaves no such record and
1161
+ reads as lost ([Resume after a shutdown](#resume-after-a-shutdown)).
1162
+
1163
+ ### Resume after a shutdown
1164
+
1165
+ After a shutdown, a reboot or a crash (OATS 0.69, #1559), `oats session
1166
+ resume` brings back every instance session that OATS saw alive and then lost
1167
+ ([Which losses come back](#which-losses-come-back)), on every deployment in
1168
+ this computer's list
1169
+ ([workspaces.md](workspaces.md#this-computers-deployments)), each in its own
1170
+ harness conversation, with the launch it recorded. OATS Desktop and `oats
1171
+ tui` run it once when they open. Running instances are left alone; instances
1172
+ stopped with OATS, or whose harness ended by itself, stay stopped. Stopping an
1173
+ instance with OATS is the only way to keep it down: nothing opts a deployment
1174
+ or an instance out of the sweep.
1175
+
1176
+ #### How a session's end is read
1177
+
1178
+ A launched home that does not run reads one of three ends, `sessionEnd` on
1179
+ its status row ([desktop-cli-api.md](desktop-cli-api.md#row-session-end)),
1180
+ for its current start (`startId` in `instance.json`):
1181
+
1182
+ | What the home holds for its current start | `sessionEnd` | Resumed |
1183
+ |---|---|---|
1184
+ | a stop's record that names it (or, a record from before 0.69, written after the start) | `stopped` | no |
1185
+ | an exit marker that names it with an exit status below 128 (`/exit`, Ctrl-C handled by the harness, its own error), or the marker of a kernel before 0.69 | `exited` | no: the row offers Start, as before |
1186
+ | an exit marker that names it with a signal's status (128 and up: the harness alone was killed, an out-of-memory kill for example) | `lost` | when the sweep can vouch for the loss ([below](#which-losses-come-back)) |
1187
+ | neither (the host went down, or the tmux server died under the live harness) | `lost` | when the sweep can vouch for the loss |
1188
+
1189
+ The window a spawn or a start makes writes the exit marker,
1190
+ `.oats-start-exited`, when the harness exits; `oats instance stop` writes its
1191
+ record, `.oats-stop.json`. Both are kernel-private files of the home, not a
1192
+ contract: read `sessionEnd`. A shutdown kills the window's shell with the
1193
+ harness, so a lost session leaves no marker. A home spawned before 0.69 and
1194
+ never restarted since names no start: it reads `stopped` only after a stop,
1195
+ and otherwise `lost`, also when its harness ended by itself. It comes back only
1196
+ when OATS saw it running since the upgrade, so one that ended before the
1197
+ upgrade stays down, and one that ends by itself after it comes back once
1198
+ (stop it with OATS to keep it down). Its next start records the markers.
1199
+
1200
+ #### What a resume runs
1201
+
1202
+ `oats session start --resume --home <abs>` runs the recorded recipe as an
1203
+ ordinary start does: the same locks and checks, the same harness, model,
1204
+ launch configuration, environment and yolo, and the launch hooks again under
1205
+ the settings captured at spawn (which is how a messaging capability's
1206
+ delivery comes back). It refuses a home that did not lose its session
1207
+ (`E_RESUME_NOT_LOST`) and a launch choice (`E_BAD_ARGS`). Two things differ:
1208
+
1209
+ - **The conversation.** The newest transcript whose recorded cwd is the home
1210
+ itself, written since the home was created, in the locations its
1211
+ native-record receipts name: Claude gets `--resume <id>`, pi `--session
1212
+ <id>`. "Since the home was created" keeps an earlier instance of the same
1213
+ name, at the same path, out. Only the window runs the selector:
1214
+ `instance.json`, the pending receipt and the recipe keep the ordinary
1215
+ launch, so a later Start opens a fresh conversation.
1216
+ - **The prompt.** In place of the task prompt the harness gets one line:
1217
+ "OATS resumed this session after it was lost (the host restarted or its
1218
+ terminal server ended). Continue from where you were." A harness cut off
1219
+ mid-turn would otherwise wait for someone to type.
1220
+
1221
+ No conversation found (never filed, deleted, or no receipt names where it
1222
+ went): the ordinary fresh start on `TASK.md`, answered `resumed: false` with
1223
+ the reason. **Codex is never resumed yet:** a Codex home takes that fresh
1224
+ start, reason `resume-unproven`, until a Codex resume is proven end to end on
1225
+ a signed-in host.
1226
+
1227
+ #### The launch environment a resume runs under
1228
+
1229
+ A resume starts only under the `{fromEnv: SRC}` values the start it brings
1230
+ back ran with. Every start that renders a recipe, the spawn's own launch
1231
+ included, records them. A resume compares them, after the check that every
1232
+ reference is set (`E_LAUNCH_ENV_MISSING`, which comes first):
1233
+
1234
+ - **A changed value** refuses the resume before anything is launched:
1235
+ `E_LAUNCH_ENV_CHANGED`, "this home's launch environment changed since its
1236
+ last start (`<NAMES>`); nothing was started: start it yourself to use the
1237
+ new values". Only the names are given, sorted, never a value. The sweep
1238
+ reports it like any refused start (`refused`, `start-refused`, the code).
1239
+ An ordinary Start or Restart never compares: it starts under the values it
1240
+ finds and records them.
1241
+ - **No record to compare with.** A home last started by an earlier kernel,
1242
+ or one whose record does not read, is resumed with one warning: "`<instance>`'s
1243
+ launch environment could not be verified this once (it was last started
1244
+ before OATS recorded it); its next start records it". That start records
1245
+ it, so the warning is given once.
1246
+ - **The environment is the one the resume runs in.** OATS Desktop runs with
1247
+ the desktop session's environment, not your shell's: a `fromEnv` variable
1248
+ exported only in a shell profile is not set there, so the Desktop's sweep
1249
+ refuses that home (`E_LAUNCH_ENV_MISSING`) while `oats tui` run from that
1250
+ shell resumes it. Put the variable in the session's environment, or use a
1251
+ literal in the launch configuration.
1252
+ - **A command you typed into the window is not resumed.** A resume runs the
1253
+ instance's OATS launch, with the launch configuration, model and yolo its
1254
+ last start chose. Put a custom command in a launch configuration.
1255
+
1256
+ The record is two kernel-private files in the home, not a contract:
1257
+ `.oats-start-env.json` holds, for one start, a keyed one-way digest
1258
+ (HMAC-SHA256) of each referenced value, and `.oats-start-env.key` (mode 0600)
1259
+ holds the key. A value, which may be a credential, is never written, and the
1260
+ key never leaves the home: a retire's recovery copy of the home leaves both
1261
+ files out. Writing the record never fails a start. A start
1262
+ that could not write it leaves its resume to the warning above.
1263
+
1264
+ #### Prompts a resume meets
1265
+
1266
+ A resume answers no prompt that an ordinary start does not:
1267
+
1268
+ - A development-channel confirmation stops a resume as it stops a start
1269
+ ([Launch prompt outcomes](#launch-prompt-outcomes)): the session is kept and
1270
+ the sweep reports it `blocked`. The approved channel route shows no prompt.
1271
+ - **Claude's resume-cost dialog.** On some plans Claude can ask, on the first
1272
+ message after resuming a long, inactive conversation, whether to resume it
1273
+ from a summary or in full. Nothing documented turns it off or answers it,
1274
+ and the choice is the person's: **OATS sends no key.** After a resumed
1275
+ Claude launch the kernel watches the pane for at most 20 seconds, and stops
1276
+ earlier once the session shows itself working. When it recognises the dialog
1277
+ the start still succeeds, answers `waiting: "resume-confirmation"`, and the
1278
+ client says the instance is waiting for its person to choose: open its
1279
+ terminal. The dialog is recognised by its option labels, taken from Claude
1280
+ Code's strings and documentation (`lib/launch-prompt-fixtures/README.md`);
1281
+ a screen it does not recognise is not a block.
1282
+
1283
+ #### Which losses come back
1284
+
1285
+ The sweep resumes a lost home only when OATS can vouch for the loss, from
1286
+ what its own reads of that home saw (`oats status`, OATS Desktop and `oats
1287
+ tui` reading it, and the sweep's own read). All four must hold:
1288
+
1289
+ 1. OATS saw the home running for its current start.
1290
+ 2. No earlier sweep answered this loss. A sweep answers each lost home once,
1291
+ whatever it did with it (resumed, started fresh, blocked, refused or
1292
+ skipped). A status read never uses a loss up, and `--plan` answers none.
1293
+ 3. OATS first saw it not running less than 24 hours ago.
1294
+ 4. Within one boot, OATS first saw it not running less than 24 hours after it
1295
+ last saw it running. Across a reboot this one does not apply.
1296
+
1297
+ Any other lost home is reported `skipped`, `not-seen-recently`, with the
1298
+ reason, and nothing is started; its status row still reads `sessionEnd:
1299
+ lost`, and `oats session start --resume --home <abs>` run by hand still
1300
+ resumes it. So:
1301
+
1302
+ - a harness killed by an out-of-memory kill at 02:00 and seen by a status at
1303
+ 02:01 comes back at a 09:00 sweep;
1304
+ - a computer off for two weeks brings back what ran when it went down, at the
1305
+ first client that opens;
1306
+ - a tmux server that crashed overnight brings its instances back at the
1307
+ morning's first client;
1308
+ - **an agent killed outside OATS (closed from tmux, or killed by a signal)
1309
+ comes back within 24 hours: only `oats instance stop` keeps it down;**
1310
+ - a loss first seen a day ago or more, or a session that died before any read
1311
+ of OATS saw it run, stays down.
1312
+
1313
+ Two limits follow from reading only what OATS saw:
1314
+
1315
+ - **After upgrading to 0.69**, open OATS Desktop or `oats tui`, or run `oats
1316
+ status`, once before you restart the computer, or nothing from before the
1317
+ upgrade comes back.
1318
+ - A whole boot with no OATS read leaves that boot unknown: what ran in it and
1319
+ was lost there is not resumed.
1320
+
1321
+ Without a boot id (neither Linux nor macOS: both have one), clause 4 applies
1322
+ to every loss and the 3-resumes-per-boot guard (below) is off.
1323
+
1324
+ **Status records what it sees.** Every local listing of a deployment's
1325
+ instances (`oats status`, and every command that lists them) records, per
1326
+ home, its current start, when it was last seen running, when it was first
1327
+ seen not running, the boot of each, and whether a sweep answered the loss. It
1328
+ goes in a kernel-private file, one per deployment,
1329
+ `session-resume/seen/<16 hex>.json` under `~/.oats` (`$OATS_HOME_DIR` when
1330
+ set), beside the sweep's per-boot note; it is not a contract. Writing it never
1331
+ changes what status answers, prints nothing, and is skipped when nothing
1332
+ changed: a running home's last look is rewritten at most every 10 minutes in
1333
+ a boot. A record that cannot be read counts as empty, which resumes nothing,
1334
+ and is rewritten whole; one that cannot be written is left as it is. A status
1335
+ routed to another machine with `--server` records nothing on this one.
1336
+ `oats session resume --plan` records what its own read sees, as any status
1337
+ read does, and answers no loss. The three figures are constants of the
1338
+ kernel (`lib/session-seen.mjs`).
1339
+
1340
+ #### The sweep
1341
+
1342
+ `oats session resume` reads this computer's list of deployments and never
1343
+ writes it, and skips a deployment `oats deployments remove` took out of it;
1344
+ `--deployment <dir>` sweeps one directory, listed or not. It starts each lost
1345
+ home it can vouch for with `--resume` in that home's own deployment scope, at
1346
+ most 4 at once. What it answers a lost home, the first that applies: not
1347
+ seen recently; refused this boot; keeps getting lost; started.
1348
+ `--plan` says what it would do and starts nothing. Its answer is in
1349
+ [desktop-cli-api.md](desktop-cli-api.md#the-machine-sweep-oats-session-resume).
1350
+
1351
+ - One sweep runs per machine: a second one answers `E_RESUME_BUSY`. A lock
1352
+ left by a process that is gone, or by another boot, is taken over.
1353
+ - A loss is answered once: whatever a sweep did with it (resumed, refused,
1354
+ skipped or blocked), no later sweep starts it again, in this boot or after
1355
+ a reboot; a later sweep reports it `not-seen-recently`. A refused resume is
1356
+ never retried automatically: it is also noted for the boot, and reported
1357
+ `refused-this-boot` should that answer be lost.
1358
+ - A home is started by sweeps at most 3 times in a boot. A home lost again
1359
+ after each resume (a harness that crashes the host or its terminal server,
1360
+ say) is then reported `keeps-getting-lost`, and that loss is answered: no
1361
+ sweep starts it again, after a reboot either. Start it by hand: its next
1362
+ loss is a new one, with a new count in each boot. Every sweep start that launched
1363
+ something counts (resumed, fresh or blocked), by home, as soon as that start
1364
+ has answered, so a sweep killed while other starts run has counted it; a
1365
+ refused, skipped or busy one does not. `oats session start --resume` run by hand is neither
1366
+ bounded nor counted.
1367
+ - The boot is the boot id on Linux and the boot time on macOS. Elsewhere there
1368
+ is no boot: nothing is noted or counted, and every sweep tries again.
1369
+ - The lock, the per-boot note and the record of what status saw live in
1370
+ `session-resume/` under `~/.oats` (`$OATS_HOME_DIR` when set). All three
1371
+ are kernel-private, not a contract.
1372
+ - Local only: a client does not resume a server's instances. A server runs
1373
+ `oats session resume` itself.
1374
+
1036
1375
  ### Inspect, input and attach
1037
1376
 
1038
1377
  ```sh
@@ -1046,12 +1385,17 @@ oats session attach --home /abs/home --detach-key 'C-\'
1046
1385
  harness, `shell` for a fallback shell,
1047
1386
  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
1048
1387
  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
1388
+ When the window is there, it also reports `paneId`, the tmux id (`%N`) of
1389
+ the agent's pane ([which pane is the agent's](#which-pane-is-the-agents)),
1390
+ a retained dead pane included.
1049
1391
  With feature `session-inspect-size` in `oats version --json`, a present
1050
1392
  terminal also reports `size: { cols, rows }`: positive integer window width
1051
1393
  and height in cells. The kernel reads tmux's `window_width` and
1052
1394
  `window_height` in the same call as the pane identity, so a viewer can open
1053
1395
  its PTY at the window's current size without constructing a tmux target.
1054
- Split windows remain refused. `size` is absent when `present` is false,
1396
+ A window with several panes still reports the window's size; one where
1397
+ OATS cannot tell which pane is the agent's is refused
1398
+ ([which pane is the agent's](#which-pane-is-the-agents)). `size` is absent when `present` is false,
1055
1399
  including a retained dead pane. Malformed dimensions are an
1056
1400
  `E_SESSION_UNAVAILABLE` error containing `invalid tmux pane response`.
1057
1401
  `session inspect --server <id> --home <home> --json` relays the execution
@@ -1082,8 +1426,9 @@ oats session attach --home /abs/home --detach-key 'C-\'
1082
1426
  for input, nor that it consumed a wake, and it does not prove which
1083
1427
  executable runs if a process inside the pane was replaced. When the backend
1084
1428
  cannot be read, a required process-table read for an explicitly labelled
1085
- shell fails, or the pane answer is
1086
- malformed or split, inspect is an error as before, never `running: false`.
1429
+ shell fails, the pane answer is
1430
+ malformed, or OATS cannot tell which of the window's panes is the agent's,
1431
+ inspect is an error as before, never `running: false`.
1087
1432
  That includes a tmux server that is gone (`no server running on` its
1088
1433
  socket, as after a reboot): status reads that row as `running: false`, and
1089
1434
  inspect answers `E_SESSION_UNAVAILABLE`. Wherever inspect answers, its
@@ -1109,8 +1454,10 @@ oats session attach --home /abs/home --detach-key 'C-\'
1109
1454
  `details.fields`.
1110
1455
  - **input** sends UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
1111
1456
  NUL) as exactly one bracketed paste followed by exactly one Enter. The text
1112
- is never run by a shell. Existing endpoint authority, fallback-shell,
1113
- stopped-session and split-window checks still refuse before input.
1457
+ is never run by a shell. Existing endpoint authority, fallback-shell and
1458
+ stopped-session checks, and a window where OATS cannot tell which pane is
1459
+ the agent's, still refuse before input. The text goes to the agent's pane
1460
+ (`paneId`), even when the person's focus is in another pane of the window.
1114
1461
 
1115
1462
  Before Enter, a size-based floor (200 ms plus 3 ms per KiB) and read-only
1116
1463
  settling polls share one **monotonic 2-second observation budget**, starting
@@ -1138,7 +1485,14 @@ oats session attach --home /abs/home --detach-key 'C-\'
1138
1485
  operations, not model processing. Broker delivery/ack policy and harness
1139
1486
  acceptance evidence remain separate contracts.
1140
1487
  - **attach** is interactive and takes no `--json`. It opens a temporary tmux
1141
- session linked to the agent's window alone.
1488
+ session linked to the agent's window alone. The viewer shows the whole
1489
+ window, every pane. When the window has more than one pane, the viewer
1490
+ selects the agent's pane before its client attaches, so typing goes to the
1491
+ agent. The viewer has no key or click that moves to another pane: a pane
1492
+ split off while a viewer is open is the active one, and takes its keys,
1493
+ until it closes. A window where OATS cannot tell
1494
+ which pane is the agent's is refused
1495
+ ([which pane is the agent's](#which-pane-is-the-agents)).
1142
1496
  Closing the viewer leaves the agent running. When the agent's window ends
1143
1497
  (for example, the instance is stopped or retired), the viewer ends too: it
1144
1498
  sets tmux's `detach-on-destroy on` for its own session, so a server
@@ -1160,14 +1514,15 @@ oats session attach --home /abs/home --detach-key 'C-\'
1160
1514
  another client) is not seen by that hook: `oats` removes the viewer as it
1161
1515
  ends, or, if `oats` has died, the next attach's sweep does. The viewer never uses
1162
1516
  `destroy-unattached`: on tmux 3.4 it crashes the agents' server when another
1163
- client detaches the viewer. A keyed viewer's key table (below)
1164
- belongs to the server, not to the session, and its `client-detached` hook
1165
- unbinds the table as it kills the session. For a viewer session that ends
1166
- another way (its agent's window ends, a `kill-session`), a keyed viewer sets
1167
- one global hook entry on the agents' server, `session-closed[900]`: when a
1168
- session whose name is a viewer's closes, the entry unbinds the key table of
1169
- that name. It is the only global hook entry OATS owns there.
1170
- Every keyed viewer sets the same entry again, which leaves it unchanged,
1517
+ client detaches the viewer. A viewer's key tables (below) belong to the
1518
+ server, not to the session, and its `client-detached` hook unbinds them as
1519
+ it kills the session. For a viewer session that ends another way (its
1520
+ agent's window ends, a `kill-session`), every viewer sets one global hook
1521
+ entry on the agents' server, `session-closed[900]`: when a session whose
1522
+ name is a viewer's closes, the entry unbinds the key table of that name
1523
+ and its `C-b` table, `<name>-prefix`. It is the only global hook entry
1524
+ OATS owns there.
1525
+ Every viewer sets the same entry again, which leaves it unchanged,
1171
1526
  and no other index is touched. Keep your own `session-closed` hooks
1172
1527
  (`set-hook -g` in `~/.tmux.conf`) at other indexes: an entry of yours at
1173
1528
  900 is replaced. A global `client-detached` hook of yours does not run
@@ -1179,12 +1534,14 @@ oats session attach --home /abs/home --detach-key 'C-\'
1179
1534
 
1180
1535
  - a viewer session (`oatsview-<pid>-<8 hex>`) with no client attached,
1181
1536
  whose attaching process, the pid in its name, no longer exists;
1182
- - a viewer key table whose session no longer exists.
1537
+ - a viewer key table whose session no longer exists, a viewer's `C-b`
1538
+ table (`<name>-prefix`) included.
1183
1539
 
1184
1540
  The sweep keeps a viewer whose attach is alive, even with no client: its
1185
1541
  client may not have attached yet. It also never removes an attached
1186
- viewer, anything not named as a viewer, or the `oatsview-locked` table
1187
- that every viewer without a key shares. When it removed something, the
1542
+ viewer, or anything not named as a viewer, such as the server-wide
1543
+ `oatsview-locked` and `oatsview-locked-prefix` tables of an earlier
1544
+ kernel. When it removed something, the
1188
1545
  attach prints one line on stderr before the viewer opens:
1189
1546
  `oats: removed <n> leftover viewer session(s) and <m> key table(s) of
1190
1547
  earlier attaches`. A failed sweep is not the attach's failure; the next
@@ -1198,8 +1555,100 @@ oats session attach --home /abs/home --detach-key 'C-\'
1198
1555
  no version it can read, the client starts as before. A routed attach
1199
1556
  (`--server`) runs the same viewer on the host, so the host's tmux decides.
1200
1557
 
1558
+ **Scrolling back.** Every viewer, with or without a detach key, has the
1559
+ mouse on in its own session (the agents' session and the operator's tmux
1560
+ settings are untouched). The wheel then puts the agent's pane in tmux's
1561
+ copy mode and scrolls it. An agent that has asked for mouse reports, as
1562
+ Claude Code's fullscreen mode does, gets the wheel instead, and scrolls
1563
+ its own screen. `Shift+PageUp` (tmux's `S-PageUp`) puts the agent's
1564
+ pane in tmux's copy mode, a page up, in every viewer, with or without a
1565
+ detach key, even when the agent has taken the mouse (Claude Code does, and
1566
+ then the wheel goes to it). In copy mode tmux's own copy-mode keys apply:
1567
+ `PageUp` and `PageDown` move a page, and `q` leaves it. The agent never
1568
+ receives `Shift+PageUp` while a viewer is attached.
1569
+
1570
+ **`C-b [` in a viewer without a detach key**
1571
+ ([#1502](https://github.com/awebai/oats/issues/1502)) also enters copy mode, as a tmux prefix does, for a keyboard that has no
1572
+ PageUp. It is the viewer's only `C-b` key:
1573
+ - every other key after `C-b` reaches the agent as both keys, in order:
1574
+ `C-b n`, `C-b c` and `C-b C-b` arrive as typed;
1575
+ - the wheel, a drag and `Shift+PageUp` after `C-b` send the `C-b`, then do
1576
+ what they do alone;
1577
+ - a mouse report after `C-b` reaches an agent that asked for one.
1578
+ `C-b` waits for the next key with no timeout: tmux holds the client in the
1579
+ viewer's `C-b` table for that one key.
1580
+
1581
+ **Every viewer's tables are its own.** A viewer reads a key table named
1582
+ as its session (`oatsview-<pid>-<8 hex>`), and a viewer without a detach
1583
+ key has its `C-b` table beside it, `<session>-prefix`. Both are bound
1584
+ once, when the viewer is made and before a client reads them, and are
1585
+ removed with the session: by the viewer's cleanup, its `client-detached`
1586
+ hook, the `session-closed[900]` entry and the next attach's sweep. No
1587
+ other viewer's opening touches them, and a key a `tmux.conf` or another
1588
+ program binds in some other table is never run. A server-wide
1589
+ `oatsview-locked` or `oatsview-locked-prefix` that an earlier kernel left
1590
+ is not a viewer's: it is left as it is, and no viewer reads it. A keyed
1591
+ viewer has no `C-b` key; its caller chooses its keys.
1592
+
1593
+ **A tmux limitation: a `C-b` pressed as another viewer opens is lost.**
1594
+ Setting any session's `key-table` option returns every client of the
1595
+ server to its default table. tmux does this in `options.c` (the
1596
+ `key-table` case runs `server_client_set_key_table(loop, NULL)` for every
1597
+ client: tmux 3.3, 3.4 and 3.8 alike), and every new viewer sets its own.
1598
+ So a `C-b` pressed in the instant another viewer of the same server opens
1599
+ is dropped, and the key after it reaches the agent alone. A test pins
1600
+ this as known behaviour (`test/session-attach-detach-key.test.mjs`,
1601
+ "KNOWN tmux LIMITATION").
1602
+
1603
+ **Only on tmux 3.3 and later** (`VIEWER_PREFIX_MIN_TMUX`). The forwarding
1604
+ below needs a `send-keys` that names no key to send the key it is bound
1605
+ to, which tmux has from 3.3 (its CHANGES, "3.2a to 3.3": "Make send-keys
1606
+ without arguments send the key it is bound to (if bound to a key)"). On
1607
+ tmux 3.0 to 3.2a such a `send-keys` sends nothing, and the key after `C-b`
1608
+ would be lost. There the viewer has no `C-b` key: `C-b` reaches the agent
1609
+ as any key does, and the wheel and `Shift+PageUp` scroll back. The viewer
1610
+ asks `tmux -V` once, before it binds anything. A release `tmux X.Y` is
1611
+ read as X.Y, and a development build `tmux next-X.Y` as X.Y too. Anything
1612
+ else (`tmux master`, no answer) means no `C-b` key. Checked on tmux 3.8.
1613
+
1614
+ How a key after `C-b` is forwarded, exactly (for a client that builds its
1615
+ own viewer, as the Desktop's local one does: `lib/session-viewer.mjs`
1616
+ exports the tables as data, `VIEWER_BINDINGS`, `PREFIX_KEY`,
1617
+ `PREFIX_TABLE_SUFFIX` and `LOCKED_PREFIX_BINDINGS`):
1618
+ - The viewer's table binds `C-b` to `switch-client -T <session>-prefix`.
1619
+ - That table binds `[` to `copy-mode`. It binds `WheelUpPane`,
1620
+ `MouseDrag1Pane` and `S-PageUp` to `send-keys C-b ;` followed by the
1621
+ viewer table's own command for that key.
1622
+ - It binds `Any`, which tmux runs for every key with no binding of its
1623
+ own, to
1624
+ `send-keys C-b ; if-shell -F '#{!=:#{mouse_x},}' 'send-keys -M' 'send-keys'`.
1625
+ The `C-b` goes to the agent first. A mouse event, the only key that sets
1626
+ `mouse_x`, then goes as one with `-M`. Any other key goes through a
1627
+ `send-keys` that names no key, which sends the key the command is bound
1628
+ to. tmux(1) (3.8), `send-keys`: "If no keys are given and the command is
1629
+ bound to a key, then that key is used."
1630
+
1631
+ **The status line.** A viewer without a detach key shows one line under
1632
+ the agent, `Shift+PgUp or C-b [ to scroll back` (`Shift+PgUp to scroll
1633
+ back` where it has no `C-b` key), so the person reading the agent can see
1634
+ how to scroll back: nobody guesses a key. It takes the
1635
+ client's last row. `--no-status-line` (feature
1636
+ `session-attach-no-status-line`) drops it, for a caller that shows
1637
+ the keys itself (`oats tui`); the keys stay. A routed attach sends
1638
+ `--no-status-line` as it is: a host without
1639
+ `session-attach-no-status-line` ignores it and shows the line. A keyed
1640
+ viewer has no status line.
1641
+
1642
+ **Copy mode is the pane's, not the viewer's.** It is a mode of the agent's
1643
+ pane on the agents' tmux server. While one viewer is scrolled back, every
1644
+ other viewer of that agent (the Desktop, a second `oats tui`, another
1645
+ `oats session attach`) shows the same frozen screen, and keys typed in any
1646
+ of them go to copy mode until it is left (`q`, or scrolling back to the
1647
+ bottom).
1648
+
1201
1649
  **Leaving the viewer.** Without `--detach-key` there is no keyboard exit:
1202
- every key goes to the agent, the tmux prefix included. Close the terminal.
1650
+ every other key goes to the agent, the tmux prefix included (after `C-b`,
1651
+ as both keys). Close the terminal.
1203
1652
  With `--detach-key <key>` (`--detach-key=<key>` is the same; feature
1204
1653
  `session-attach-detach-key`, OATS 0.51.0), pressing `<key>` detaches that
1205
1654
  viewer's client. The agent's window and every other viewer are untouched.
@@ -1231,8 +1680,8 @@ oats session attach --home /abs/home --detach-key 'C-\'
1231
1680
  kernel does not judge whether a harness reads the key: that is the
1232
1681
  caller's choice.
1233
1682
 
1234
- **While the pane is scrolled back.** The viewer's wheel and drag bindings
1235
- put the pane in tmux's copy mode, and there copy mode's key table is read
1683
+ **While the pane is scrolled back.** The viewer's wheel, drag and
1684
+ `Shift+PageUp` bindings put the pane in tmux's copy mode, and there copy mode's key table is read
1236
1685
  before the viewer's. A detach key that copy mode binds acts in copy mode
1237
1686
  and does not detach; it detaches once the mode is left (`q`, or scrolling
1238
1687
  back to the bottom). The grammar does not exclude those keys. The
@@ -1295,10 +1744,13 @@ removed with the home.
1295
1744
 
1296
1745
  Spawn writes `TASK.md` in the home: the instance's name, soul, home and work
1297
1746
  tree, followed by the `--task` or `--task-file` text, or a note to await
1298
- instructions when no task is given. Every launch, including `session start`
1299
- and `restart`, opens a new harness conversation on `TASK.md`. The instance
1300
- resumes its work from its own state files, as its knowledge capability
1301
- prescribes.
1747
+ instructions when no task is given. Every launch, `session start` and
1748
+ `restart` included, opens a fresh harness conversation on `TASK.md`, **except a
1749
+ resume** ([Resume after a shutdown](#resume-after-a-shutdown)), which continues
1750
+ the instance's own last conversation with a one-line resume notice. This
1751
+ replaces the earlier rule that every start, without exception, opened a new
1752
+ conversation (OATS 0.69, #1559). In a fresh conversation the instance resumes
1753
+ its work from its own state files, as its knowledge capability prescribes.
1302
1754
 
1303
1755
  The task's text never travels on a command line, where any local user could
1304
1756
  read it in the process list: