@awebai/oats 0.68.1 → 0.69.2

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 (99) hide show
  1. package/bin/oats.mjs +180 -36
  2. package/docs/capabilities.md +73 -10
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/configuration.md +68 -2
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  6. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  7. package/docs/desktop-cli-api.md +600 -25
  8. package/docs/desktop-instance-start.md +59 -3
  9. package/docs/desktop.md +175 -10
  10. package/docs/execution-targets.md +536 -62
  11. package/docs/harness-trust.md +3 -1
  12. package/docs/implementation.md +33 -15
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge.md +25 -16
  15. package/docs/oats-local.schema.json +2 -2
  16. package/docs/official-catalog.md +6 -5
  17. package/docs/packages.md +14 -14
  18. package/docs/release-notes/v0.69.0.md +658 -0
  19. package/docs/release-notes/v0.69.1.md +25 -0
  20. package/docs/release-notes/v0.69.2.md +259 -0
  21. package/docs/servers.md +51 -7
  22. package/docs/soul.schema.json +1 -0
  23. package/docs/souls-and-instances.md +46 -9
  24. package/docs/tui.md +177 -21
  25. package/docs/upgrading.md +16 -7
  26. package/docs/workspaces.md +2 -2
  27. package/injects/instance-boundary.md +19 -33
  28. package/injects/work-attached.md +8 -13
  29. package/injects/work-checkout.md +16 -30
  30. package/injects/work-directory.md +9 -15
  31. package/injects/work-workspace.md +8 -19
  32. package/injects/work-worktree.md +18 -33
  33. package/lib/capability-contract.mjs +2 -2
  34. package/lib/core.mjs +496 -127
  35. package/lib/file-pieces.mjs +49 -0
  36. package/lib/instance-background.mjs +54 -0
  37. package/lib/instance-events.mjs +25 -4
  38. package/lib/instance-inspect.mjs +3 -0
  39. package/lib/instance-lifecycle.mjs +35 -0
  40. package/lib/instance-resolution.mjs +3 -2
  41. package/lib/instance-same-work.mjs +67 -0
  42. package/lib/instance-upgrade.mjs +18 -0
  43. package/lib/launch-prompt-fixtures/README.md +62 -0
  44. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  45. package/lib/launch-prompt-fixtures.mjs +49 -0
  46. package/lib/launch-prompt-resume.mjs +55 -0
  47. package/lib/login-environment.mjs +27 -9
  48. package/lib/materialize.mjs +23 -2
  49. package/lib/resolve.mjs +32 -5
  50. package/lib/schedule.mjs +3 -3
  51. package/lib/servers.mjs +136 -27
  52. package/lib/session-end.mjs +82 -0
  53. package/lib/session-input.mjs +43 -9
  54. package/lib/session-resume-contract.mjs +33 -0
  55. package/lib/session-resume.mjs +337 -0
  56. package/lib/session-seen.mjs +163 -0
  57. package/lib/session-viewer.mjs +147 -44
  58. package/lib/soul-composition.mjs +15 -11
  59. package/lib/start-env.mjs +110 -0
  60. package/lib/tmux-server-scope.mjs +139 -14
  61. package/lib/workspace.mjs +41 -6
  62. package/package-catalog.json +11 -5
  63. package/package.json +1 -1
  64. package/packages/client/cli-adapter.mjs +39 -8
  65. package/packages/client/cli-locator.mjs +3 -2
  66. package/packages/client/deployment-data.mjs +16 -0
  67. package/packages/client/deployment-panel.mjs +7 -0
  68. package/packages/client/file-output-exec.mjs +98 -0
  69. package/packages/client/instance-tree.mjs +64 -14
  70. package/packages/client/launch-prompt-outcome.mjs +25 -13
  71. package/packages/client/own-codes.mjs +2 -0
  72. package/packages/client/panel-views.mjs +11 -3
  73. package/packages/client/remote-roster.mjs +5 -1
  74. package/packages/client/roster-sections.mjs +50 -6
  75. package/packages/client/same-work.mjs +49 -0
  76. package/packages/client/session-attach.mjs +35 -5
  77. package/packages/client/session-resume-cli.mjs +64 -0
  78. package/packages/client/session-resume-trigger.mjs +167 -0
  79. package/packages/client/session-resume.mjs +332 -0
  80. package/packages/client/soul-rows.mjs +2 -0
  81. package/packages/client/spawn-apply-contract.mjs +2 -1
  82. package/packages/client/spawn-decision.mjs +4 -1
  83. package/packages/client/spawn-preview-contract.mjs +12 -1
  84. package/packages/client/spawn-preview.mjs +2 -0
  85. package/packages/client/tmux-status.mjs +30 -7
  86. package/packages/client/waiting-on-you.mjs +11 -4
  87. package/packages/client/workspace-step.mjs +17 -5
  88. package/packages/record/lib/last-conversation.mjs +123 -0
  89. package/packages/record/lib/session-roots.mjs +10 -1
  90. package/packages/tui/README.md +2 -2
  91. package/packages/tui/lib/client.mjs +7 -3
  92. package/packages/tui/lib/main.mjs +49 -14
  93. package/packages/tui/lib/model.mjs +146 -55
  94. package/packages/tui/lib/store.mjs +84 -27
  95. package/packages/tui/lib/term/text.mjs +12 -9
  96. package/packages/tui/lib/views/frame.mjs +74 -7
  97. package/packages/tui/lib/views/help.mjs +10 -3
  98. package/packages/tui/lib/views/instances.mjs +41 -3
  99. 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,248 @@ 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
+ **A home OATS is stopping, upgrading or retiring, or whose retire did not
1177
+ finish, is never resumed** (OATS 0.69.2). A resume holds the home's lifecycle
1178
+ claim for its whole start, the claim a retire, a stop and an upgrade hold, so
1179
+ it never runs beside one of them, and it reads under that claim whether the
1180
+ home owes a retire and whether its session is still lost. The sweep reports
1181
+ such a home `skipped`, `lifecycle-busy`, and starts nothing; what OATS was
1182
+ doing decides what the home is next. A retire records the stop of the session
1183
+ it ends, before it ends it, so a home it was retiring reads `stopped`, never
1184
+ `lost`, even when the retire fails afterwards. The one exception is when the
1185
+ stop record itself cannot be written (a full disk) and the retire then fails
1186
+ as well: that home reads `lost`, as it did before 0.69.2.
1187
+
1188
+ #### How a session's end is read
1189
+
1190
+ A launched home that does not run reads one of three ends, `sessionEnd` on
1191
+ its status row ([desktop-cli-api.md](desktop-cli-api.md#row-session-end)),
1192
+ for its current start (`startId` in `instance.json`):
1193
+
1194
+ | What the home holds for its current start | `sessionEnd` | Resumed |
1195
+ |---|---|---|
1196
+ | a stop's record that names it (or, a record from before 0.69, written after the start) | `stopped` | no |
1197
+ | 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 |
1198
+ | 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)) |
1199
+ | neither (the host went down, or the tmux server died under the live harness) | `lost` | when the sweep can vouch for the loss |
1200
+
1201
+ The window a spawn or a start makes writes the exit marker,
1202
+ `.oats-start-exited`, when the harness exits; `oats instance stop` writes its
1203
+ record, `.oats-stop.json`, and so does a retire, before it ends the window
1204
+ (0.69.2). Both are kernel-private files of the home, not a
1205
+ contract: read `sessionEnd`. A shutdown kills the window's shell with the
1206
+ harness, so a lost session leaves no marker. A home spawned before 0.69 and
1207
+ never restarted since names no start: it reads `stopped` only after a stop,
1208
+ and otherwise `lost`, also when its harness ended by itself. It comes back only
1209
+ when OATS saw it running since the upgrade, so one that ended before the
1210
+ upgrade stays down, and one that ends by itself after it comes back once
1211
+ (stop it with OATS to keep it down). Its next start records the markers.
1212
+
1213
+ #### What a resume runs
1214
+
1215
+ `oats session start --resume --home <abs>` runs the recorded recipe as an
1216
+ ordinary start does: the same locks and checks, the same harness, model,
1217
+ launch configuration, environment and yolo, and the launch hooks again under
1218
+ the settings captured at spawn (which is how a messaging capability's
1219
+ delivery comes back). It refuses a home that did not lose its session
1220
+ (`E_RESUME_NOT_LOST`) and a launch choice (`E_BAD_ARGS`). Two things differ:
1221
+
1222
+ - **The conversation.** The newest transcript whose recorded cwd is the home
1223
+ itself, written since the home was created, in the locations its
1224
+ native-record receipts name: Claude gets `--resume <id>`, pi `--session
1225
+ <id>`. "Since the home was created" keeps an earlier instance of the same
1226
+ name, at the same path, out. Only the window runs the selector:
1227
+ `instance.json`, the pending receipt and the recipe keep the ordinary
1228
+ launch, so a later Start opens a fresh conversation.
1229
+ - **The prompt.** In place of the task prompt the harness gets one line:
1230
+ "OATS resumed this session after it was lost (the host restarted or its
1231
+ terminal server ended). Continue from where you were." A harness cut off
1232
+ mid-turn would otherwise wait for someone to type.
1233
+
1234
+ No conversation found (never filed, deleted, or no receipt names where it
1235
+ went): the ordinary fresh start on `TASK.md`, answered `resumed: false` with
1236
+ the reason. **Codex is never resumed yet:** a Codex home takes that fresh
1237
+ start, reason `resume-unproven`, until a Codex resume is proven end to end on
1238
+ a signed-in host.
1239
+
1240
+ #### The launch environment a resume runs under
1241
+
1242
+ A resume starts only under the `{fromEnv: SRC}` values the start it brings
1243
+ back ran with. Every start that renders a recipe, the spawn's own launch
1244
+ included, records them. A resume compares them, after the check that every
1245
+ reference is set (`E_LAUNCH_ENV_MISSING`, which comes first):
1246
+
1247
+ - **A changed value** refuses the resume before anything is launched:
1248
+ `E_LAUNCH_ENV_CHANGED`, "this home's launch environment changed since its
1249
+ last start (`<NAMES>`); nothing was started: start it yourself to use the
1250
+ new values". Only the names are given, sorted, never a value. The sweep
1251
+ reports it like any refused start (`refused`, `start-refused`, the code).
1252
+ An ordinary Start or Restart never compares: it starts under the values it
1253
+ finds and records them.
1254
+ - **No record to compare with.** A home last started by an earlier kernel,
1255
+ or one whose record does not read, is resumed with one warning: "`<instance>`'s
1256
+ launch environment could not be verified this once (it was last started
1257
+ before OATS recorded it); its next start records it". That start records
1258
+ it, so the warning is given once.
1259
+ - **The environment is the one the resume runs in.** OATS Desktop runs with
1260
+ the desktop session's environment, not your shell's: a `fromEnv` variable
1261
+ exported only in a shell profile is not set there, so the Desktop's sweep
1262
+ refuses that home (`E_LAUNCH_ENV_MISSING`) while `oats tui` run from that
1263
+ shell resumes it. Put the variable in the session's environment, or use a
1264
+ literal in the launch configuration.
1265
+ - **A command you typed into the window is not resumed.** A resume runs the
1266
+ instance's OATS launch, with the launch configuration, model and yolo its
1267
+ last start chose. Put a custom command in a launch configuration.
1268
+
1269
+ The record is two kernel-private files in the home, not a contract:
1270
+ `.oats-start-env.json` holds, for one start, a keyed one-way digest
1271
+ (HMAC-SHA256) of each referenced value, and `.oats-start-env.key` (mode 0600)
1272
+ holds the key. A value, which may be a credential, is never written, and the
1273
+ key never leaves the home: a retire's recovery copy of the home leaves both
1274
+ files out. Writing the record never fails a start. A start
1275
+ that could not write it leaves its resume to the warning above.
1276
+
1277
+ #### Prompts a resume meets
1278
+
1279
+ A resume answers no prompt that an ordinary start does not:
1280
+
1281
+ - A development-channel confirmation stops a resume as it stops a start
1282
+ ([Launch prompt outcomes](#launch-prompt-outcomes)): the session is kept and
1283
+ the sweep reports it `blocked`. The approved channel route shows no prompt.
1284
+ - **Claude's resume-cost dialog.** On some plans Claude can ask, on the first
1285
+ message after resuming a long, inactive conversation, whether to resume it
1286
+ from a summary or in full. Nothing documented turns it off or answers it,
1287
+ and the choice is the person's: **OATS sends no key.** After a resumed
1288
+ Claude launch the kernel watches the pane for at most 20 seconds, and stops
1289
+ earlier once the session shows itself working. When it recognises the dialog
1290
+ the start still succeeds, answers `waiting: "resume-confirmation"`, and the
1291
+ client says the instance is waiting for its person to choose: open its
1292
+ terminal. The dialog is recognised by its option labels, taken from Claude
1293
+ Code's strings and documentation (`lib/launch-prompt-fixtures/README.md`);
1294
+ a screen it does not recognise is not a block.
1295
+
1296
+ #### Which losses come back
1297
+
1298
+ The sweep resumes a lost home only when OATS can vouch for the loss, from
1299
+ what its own reads of that home saw (`oats status`, OATS Desktop and `oats
1300
+ tui` reading it, and the sweep's own read). All four must hold:
1301
+
1302
+ 1. OATS saw the home running for its current start.
1303
+ 2. No earlier sweep answered this loss. A sweep answers each lost home once,
1304
+ whatever it did with it (resumed, started fresh, blocked, refused or
1305
+ skipped), except a home it skipped because OATS was stopping, upgrading
1306
+ or retiring it. A status read never uses a loss up, and `--plan` answers
1307
+ none.
1308
+ 3. OATS first saw it not running less than 24 hours ago.
1309
+ 4. Within one boot, OATS first saw it not running less than 24 hours after it
1310
+ last saw it running. Across a reboot this one does not apply.
1311
+
1312
+ Any other lost home is reported `skipped`, `not-seen-recently`, with the
1313
+ reason, and nothing is started; its status row still reads `sessionEnd:
1314
+ lost`, and `oats session start --resume --home <abs>` run by hand still
1315
+ resumes it. So:
1316
+
1317
+ - a harness killed by an out-of-memory kill at 02:00 and seen by a status at
1318
+ 02:01 comes back at a 09:00 sweep;
1319
+ - a computer off for two weeks brings back what ran when it went down, at the
1320
+ first client that opens;
1321
+ - a tmux server that crashed overnight brings its instances back at the
1322
+ morning's first client;
1323
+ - **an agent killed outside OATS (closed from tmux, or killed by a signal)
1324
+ comes back within 24 hours: only `oats instance stop` keeps it down;**
1325
+ - a loss first seen a day ago or more, or a session that died before any read
1326
+ of OATS saw it run, stays down.
1327
+
1328
+ Two limits follow from reading only what OATS saw:
1329
+
1330
+ - **After upgrading to 0.69**, open OATS Desktop or `oats tui`, or run `oats
1331
+ status`, once before you restart the computer, or nothing from before the
1332
+ upgrade comes back.
1333
+ - A whole boot with no OATS read leaves that boot unknown: what ran in it and
1334
+ was lost there is not resumed.
1335
+
1336
+ Without a boot id (neither Linux nor macOS: both have one), clause 4 applies
1337
+ to every loss and the 3-resumes-per-boot guard (below) is off.
1338
+
1339
+ **Status records what it sees.** Every local listing of a deployment's
1340
+ instances (`oats status`, and every command that lists them) records, per
1341
+ home, its current start, when it was last seen running, when it was first
1342
+ seen not running, the boot of each, and whether a sweep answered the loss. It
1343
+ goes in a kernel-private file, one per deployment,
1344
+ `session-resume/seen/<16 hex>.json` under `~/.oats` (`$OATS_HOME_DIR` when
1345
+ set), beside the sweep's per-boot note; it is not a contract. Writing it never
1346
+ changes what status answers, prints nothing, and is skipped when nothing
1347
+ changed: a running home's last look is rewritten at most every 10 minutes in
1348
+ a boot. A record that cannot be read counts as empty, which resumes nothing,
1349
+ and is rewritten whole; one that cannot be written is left as it is. A status
1350
+ routed to another machine with `--server` records nothing on this one.
1351
+ `oats session resume --plan` records what its own read sees, as any status
1352
+ read does, and answers no loss. The three figures are constants of the
1353
+ kernel (`lib/session-seen.mjs`).
1354
+
1355
+ #### The sweep
1356
+
1357
+ `oats session resume` reads this computer's list of deployments and never
1358
+ writes it, and skips a deployment `oats deployments remove` took out of it;
1359
+ `--deployment <dir>` sweeps one directory, listed or not. It starts each lost
1360
+ home it can vouch for with `--resume` in that home's own deployment scope, at
1361
+ most 4 at once. What it answers a lost home, the first that applies: OATS
1362
+ is stopping, upgrading or retiring it, or its retire is owed
1363
+ (`lifecycle-busy`); not seen recently; refused this boot; keeps getting lost;
1364
+ started. The first is read from the home's status row, and the start's own
1365
+ claim decides when the row read missed it: a start that meets a retire, a
1366
+ stop, an upgrade or another resume is reported `lifecycle-busy` too, never
1367
+ refused. A home removed between the read and its start is reported
1368
+ `not-lost`.
1369
+ `--plan` says what it would do and starts nothing. Its answer is in
1370
+ [desktop-cli-api.md](desktop-cli-api.md#the-machine-sweep-oats-session-resume).
1371
+
1372
+ - One sweep runs per machine: a second one answers `E_RESUME_BUSY`. A lock
1373
+ left by a process that is gone, or by another boot, is taken over.
1374
+ - A loss is answered once: whatever a sweep did with it (resumed, refused,
1375
+ skipped or blocked), no later sweep starts it again, in this boot or after
1376
+ a reboot; a later sweep reports it `not-seen-recently`. A `lifecycle-busy`
1377
+ skip is the one that answers nothing: the next sweep reads the home again. A refused resume is
1378
+ never retried automatically: it is also noted for the boot, and reported
1379
+ `refused-this-boot` should that answer be lost.
1380
+ - A home is started by sweeps at most 3 times in a boot. A home lost again
1381
+ after each resume (a harness that crashes the host or its terminal server,
1382
+ say) is then reported `keeps-getting-lost`, and that loss is answered: no
1383
+ sweep starts it again, after a reboot either. Start it by hand: its next
1384
+ loss is a new one, with a new count in each boot. Every sweep start that launched
1385
+ something counts (resumed, fresh or blocked), by home, as soon as that start
1386
+ has answered, so a sweep killed while other starts run has counted it; a
1387
+ refused, skipped or busy one does not. `oats session start --resume` run by hand is neither
1388
+ bounded nor counted.
1389
+ - The boot is the boot id on Linux and the boot time on macOS. Elsewhere there
1390
+ is no boot: nothing is noted or counted, and every sweep tries again.
1391
+ - The lock, the per-boot note and the record of what status saw live in
1392
+ `session-resume/` under `~/.oats` (`$OATS_HOME_DIR` when set). All three
1393
+ are kernel-private, not a contract.
1394
+ - Local only: a client does not resume a server's instances. A server runs
1395
+ `oats session resume` itself.
1396
+
1036
1397
  ### Inspect, input and attach
1037
1398
 
1038
1399
  ```sh
@@ -1046,12 +1407,17 @@ oats session attach --home /abs/home --detach-key 'C-\'
1046
1407
  harness, `shell` for a fallback shell,
1047
1408
  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
1048
1409
  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
1410
+ When the window is there, it also reports `paneId`, the tmux id (`%N`) of
1411
+ the agent's pane ([which pane is the agent's](#which-pane-is-the-agents)),
1412
+ a retained dead pane included.
1049
1413
  With feature `session-inspect-size` in `oats version --json`, a present
1050
1414
  terminal also reports `size: { cols, rows }`: positive integer window width
1051
1415
  and height in cells. The kernel reads tmux's `window_width` and
1052
1416
  `window_height` in the same call as the pane identity, so a viewer can open
1053
1417
  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,
1418
+ A window with several panes still reports the window's size; one where
1419
+ OATS cannot tell which pane is the agent's is refused
1420
+ ([which pane is the agent's](#which-pane-is-the-agents)). `size` is absent when `present` is false,
1055
1421
  including a retained dead pane. Malformed dimensions are an
1056
1422
  `E_SESSION_UNAVAILABLE` error containing `invalid tmux pane response`.
1057
1423
  `session inspect --server <id> --home <home> --json` relays the execution
@@ -1082,8 +1448,9 @@ oats session attach --home /abs/home --detach-key 'C-\'
1082
1448
  for input, nor that it consumed a wake, and it does not prove which
1083
1449
  executable runs if a process inside the pane was replaced. When the backend
1084
1450
  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`.
1451
+ shell fails, the pane answer is
1452
+ malformed, or OATS cannot tell which of the window's panes is the agent's,
1453
+ inspect is an error as before, never `running: false`.
1087
1454
  That includes a tmux server that is gone (`no server running on` its
1088
1455
  socket, as after a reboot): status reads that row as `running: false`, and
1089
1456
  inspect answers `E_SESSION_UNAVAILABLE`. Wherever inspect answers, its
@@ -1109,8 +1476,10 @@ oats session attach --home /abs/home --detach-key 'C-\'
1109
1476
  `details.fields`.
1110
1477
  - **input** sends UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
1111
1478
  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.
1479
+ is never run by a shell. Existing endpoint authority, fallback-shell and
1480
+ stopped-session checks, and a window where OATS cannot tell which pane is
1481
+ the agent's, still refuse before input. The text goes to the agent's pane
1482
+ (`paneId`), even when the person's focus is in another pane of the window.
1114
1483
 
1115
1484
  Before Enter, a size-based floor (200 ms plus 3 ms per KiB) and read-only
1116
1485
  settling polls share one **monotonic 2-second observation budget**, starting
@@ -1138,7 +1507,14 @@ oats session attach --home /abs/home --detach-key 'C-\'
1138
1507
  operations, not model processing. Broker delivery/ack policy and harness
1139
1508
  acceptance evidence remain separate contracts.
1140
1509
  - **attach** is interactive and takes no `--json`. It opens a temporary tmux
1141
- session linked to the agent's window alone.
1510
+ session linked to the agent's window alone. The viewer shows the whole
1511
+ window, every pane. When the window has more than one pane, the viewer
1512
+ selects the agent's pane before its client attaches, so typing goes to the
1513
+ agent. The viewer has no key or click that moves to another pane: a pane
1514
+ split off while a viewer is open is the active one, and takes its keys,
1515
+ until it closes. A window where OATS cannot tell
1516
+ which pane is the agent's is refused
1517
+ ([which pane is the agent's](#which-pane-is-the-agents)).
1142
1518
  Closing the viewer leaves the agent running. When the agent's window ends
1143
1519
  (for example, the instance is stopped or retired), the viewer ends too: it
1144
1520
  sets tmux's `detach-on-destroy on` for its own session, so a server
@@ -1160,14 +1536,15 @@ oats session attach --home /abs/home --detach-key 'C-\'
1160
1536
  another client) is not seen by that hook: `oats` removes the viewer as it
1161
1537
  ends, or, if `oats` has died, the next attach's sweep does. The viewer never uses
1162
1538
  `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,
1539
+ client detaches the viewer. A viewer's key tables (below) belong to the
1540
+ server, not to the session, and its `client-detached` hook unbinds them as
1541
+ it kills the session. For a viewer session that ends another way (its
1542
+ agent's window ends, a `kill-session`), every viewer sets one global hook
1543
+ entry on the agents' server, `session-closed[900]`: when a session whose
1544
+ name is a viewer's closes, the entry unbinds the key table of that name
1545
+ and its `C-b` table, `<name>-prefix`. It is the only global hook entry
1546
+ OATS owns there.
1547
+ Every viewer sets the same entry again, which leaves it unchanged,
1171
1548
  and no other index is touched. Keep your own `session-closed` hooks
1172
1549
  (`set-hook -g` in `~/.tmux.conf`) at other indexes: an entry of yours at
1173
1550
  900 is replaced. A global `client-detached` hook of yours does not run
@@ -1179,12 +1556,14 @@ oats session attach --home /abs/home --detach-key 'C-\'
1179
1556
 
1180
1557
  - a viewer session (`oatsview-<pid>-<8 hex>`) with no client attached,
1181
1558
  whose attaching process, the pid in its name, no longer exists;
1182
- - a viewer key table whose session no longer exists.
1559
+ - a viewer key table whose session no longer exists, a viewer's `C-b`
1560
+ table (`<name>-prefix`) included.
1183
1561
 
1184
1562
  The sweep keeps a viewer whose attach is alive, even with no client: its
1185
1563
  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
1564
+ viewer, or anything not named as a viewer, such as the server-wide
1565
+ `oatsview-locked` and `oatsview-locked-prefix` tables of an earlier
1566
+ kernel. When it removed something, the
1188
1567
  attach prints one line on stderr before the viewer opens:
1189
1568
  `oats: removed <n> leftover viewer session(s) and <m> key table(s) of
1190
1569
  earlier attaches`. A failed sweep is not the attach's failure; the next
@@ -1198,8 +1577,100 @@ oats session attach --home /abs/home --detach-key 'C-\'
1198
1577
  no version it can read, the client starts as before. A routed attach
1199
1578
  (`--server`) runs the same viewer on the host, so the host's tmux decides.
1200
1579
 
1580
+ **Scrolling back.** Every viewer, with or without a detach key, has the
1581
+ mouse on in its own session (the agents' session and the operator's tmux
1582
+ settings are untouched). The wheel then puts the agent's pane in tmux's
1583
+ copy mode and scrolls it. An agent that has asked for mouse reports, as
1584
+ Claude Code's fullscreen mode does, gets the wheel instead, and scrolls
1585
+ its own screen. `Shift+PageUp` (tmux's `S-PageUp`) puts the agent's
1586
+ pane in tmux's copy mode, a page up, in every viewer, with or without a
1587
+ detach key, even when the agent has taken the mouse (Claude Code does, and
1588
+ then the wheel goes to it). In copy mode tmux's own copy-mode keys apply:
1589
+ `PageUp` and `PageDown` move a page, and `q` leaves it. The agent never
1590
+ receives `Shift+PageUp` while a viewer is attached.
1591
+
1592
+ **`C-b [` in a viewer without a detach key**
1593
+ ([#1502](https://github.com/awebai/oats/issues/1502)) also enters copy mode, as a tmux prefix does, for a keyboard that has no
1594
+ PageUp. It is the viewer's only `C-b` key:
1595
+ - every other key after `C-b` reaches the agent as both keys, in order:
1596
+ `C-b n`, `C-b c` and `C-b C-b` arrive as typed;
1597
+ - the wheel, a drag and `Shift+PageUp` after `C-b` send the `C-b`, then do
1598
+ what they do alone;
1599
+ - a mouse report after `C-b` reaches an agent that asked for one.
1600
+ `C-b` waits for the next key with no timeout: tmux holds the client in the
1601
+ viewer's `C-b` table for that one key.
1602
+
1603
+ **Every viewer's tables are its own.** A viewer reads a key table named
1604
+ as its session (`oatsview-<pid>-<8 hex>`), and a viewer without a detach
1605
+ key has its `C-b` table beside it, `<session>-prefix`. Both are bound
1606
+ once, when the viewer is made and before a client reads them, and are
1607
+ removed with the session: by the viewer's cleanup, its `client-detached`
1608
+ hook, the `session-closed[900]` entry and the next attach's sweep. No
1609
+ other viewer's opening touches them, and a key a `tmux.conf` or another
1610
+ program binds in some other table is never run. A server-wide
1611
+ `oatsview-locked` or `oatsview-locked-prefix` that an earlier kernel left
1612
+ is not a viewer's: it is left as it is, and no viewer reads it. A keyed
1613
+ viewer has no `C-b` key; its caller chooses its keys.
1614
+
1615
+ **A tmux limitation: a `C-b` pressed as another viewer opens is lost.**
1616
+ Setting any session's `key-table` option returns every client of the
1617
+ server to its default table. tmux does this in `options.c` (the
1618
+ `key-table` case runs `server_client_set_key_table(loop, NULL)` for every
1619
+ client: tmux 3.3, 3.4 and 3.8 alike), and every new viewer sets its own.
1620
+ So a `C-b` pressed in the instant another viewer of the same server opens
1621
+ is dropped, and the key after it reaches the agent alone. A test pins
1622
+ this as known behaviour (`test/session-attach-detach-key.test.mjs`,
1623
+ "KNOWN tmux LIMITATION").
1624
+
1625
+ **Only on tmux 3.3 and later** (`VIEWER_PREFIX_MIN_TMUX`). The forwarding
1626
+ below needs a `send-keys` that names no key to send the key it is bound
1627
+ to, which tmux has from 3.3 (its CHANGES, "3.2a to 3.3": "Make send-keys
1628
+ without arguments send the key it is bound to (if bound to a key)"). On
1629
+ tmux 3.0 to 3.2a such a `send-keys` sends nothing, and the key after `C-b`
1630
+ would be lost. There the viewer has no `C-b` key: `C-b` reaches the agent
1631
+ as any key does, and the wheel and `Shift+PageUp` scroll back. The viewer
1632
+ asks `tmux -V` once, before it binds anything. A release `tmux X.Y` is
1633
+ read as X.Y, and a development build `tmux next-X.Y` as X.Y too. Anything
1634
+ else (`tmux master`, no answer) means no `C-b` key. Checked on tmux 3.8.
1635
+
1636
+ How a key after `C-b` is forwarded, exactly (for a client that builds its
1637
+ own viewer, as the Desktop's local one does: `lib/session-viewer.mjs`
1638
+ exports the tables as data, `VIEWER_BINDINGS`, `PREFIX_KEY`,
1639
+ `PREFIX_TABLE_SUFFIX` and `LOCKED_PREFIX_BINDINGS`):
1640
+ - The viewer's table binds `C-b` to `switch-client -T <session>-prefix`.
1641
+ - That table binds `[` to `copy-mode`. It binds `WheelUpPane`,
1642
+ `MouseDrag1Pane` and `S-PageUp` to `send-keys C-b ;` followed by the
1643
+ viewer table's own command for that key.
1644
+ - It binds `Any`, which tmux runs for every key with no binding of its
1645
+ own, to
1646
+ `send-keys C-b ; if-shell -F '#{!=:#{mouse_x},}' 'send-keys -M' 'send-keys'`.
1647
+ The `C-b` goes to the agent first. A mouse event, the only key that sets
1648
+ `mouse_x`, then goes as one with `-M`. Any other key goes through a
1649
+ `send-keys` that names no key, which sends the key the command is bound
1650
+ to. tmux(1) (3.8), `send-keys`: "If no keys are given and the command is
1651
+ bound to a key, then that key is used."
1652
+
1653
+ **The status line.** A viewer without a detach key shows one line under
1654
+ the agent, `Shift+PgUp or C-b [ to scroll back` (`Shift+PgUp to scroll
1655
+ back` where it has no `C-b` key), so the person reading the agent can see
1656
+ how to scroll back: nobody guesses a key. It takes the
1657
+ client's last row. `--no-status-line` (feature
1658
+ `session-attach-no-status-line`) drops it, for a caller that shows
1659
+ the keys itself (`oats tui`); the keys stay. A routed attach sends
1660
+ `--no-status-line` as it is: a host without
1661
+ `session-attach-no-status-line` ignores it and shows the line. A keyed
1662
+ viewer has no status line.
1663
+
1664
+ **Copy mode is the pane's, not the viewer's.** It is a mode of the agent's
1665
+ pane on the agents' tmux server. While one viewer is scrolled back, every
1666
+ other viewer of that agent (the Desktop, a second `oats tui`, another
1667
+ `oats session attach`) shows the same frozen screen, and keys typed in any
1668
+ of them go to copy mode until it is left (`q`, or scrolling back to the
1669
+ bottom).
1670
+
1201
1671
  **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.
1672
+ every other key goes to the agent, the tmux prefix included (after `C-b`,
1673
+ as both keys). Close the terminal.
1203
1674
  With `--detach-key <key>` (`--detach-key=<key>` is the same; feature
1204
1675
  `session-attach-detach-key`, OATS 0.51.0), pressing `<key>` detaches that
1205
1676
  viewer's client. The agent's window and every other viewer are untouched.
@@ -1231,8 +1702,8 @@ oats session attach --home /abs/home --detach-key 'C-\'
1231
1702
  kernel does not judge whether a harness reads the key: that is the
1232
1703
  caller's choice.
1233
1704
 
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
1705
+ **While the pane is scrolled back.** The viewer's wheel, drag and
1706
+ `Shift+PageUp` bindings put the pane in tmux's copy mode, and there copy mode's key table is read
1236
1707
  before the viewer's. A detach key that copy mode binds acts in copy mode
1237
1708
  and does not detach; it detaches once the mode is left (`q`, or scrolling
1238
1709
  back to the bottom). The grammar does not exclude those keys. The
@@ -1295,10 +1766,13 @@ removed with the home.
1295
1766
 
1296
1767
  Spawn writes `TASK.md` in the home: the instance's name, soul, home and work
1297
1768
  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.
1769
+ instructions when no task is given. Every launch, `session start` and
1770
+ `restart` included, opens a fresh harness conversation on `TASK.md`, **except a
1771
+ resume** ([Resume after a shutdown](#resume-after-a-shutdown)), which continues
1772
+ the instance's own last conversation with a one-line resume notice. This
1773
+ replaces the earlier rule that every start, without exception, opened a new
1774
+ conversation (OATS 0.69, #1559). In a fresh conversation the instance resumes
1775
+ its work from its own state files, as its knowledge capability prescribes.
1302
1776
 
1303
1777
  The task's text never travels on a command line, where any local user could
1304
1778
  read it in the process list: