@awebai/oats 0.68.0 → 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.
- package/bin/oats.mjs +102 -22
- package/docs/capabilities.md +49 -5
- package/docs/configuration.md +68 -2
- package/docs/desktop-cli-api.md +355 -12
- package/docs/desktop-instance-start.md +88 -3
- package/docs/desktop.md +147 -13
- package/docs/execution-targets.md +514 -62
- package/docs/harness-trust.md +3 -1
- package/docs/implementation.md +28 -11
- package/docs/integrations.md +1 -1
- package/docs/oats-local.schema.json +2 -2
- package/docs/official-catalog.md +4 -3
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.68.1.md +102 -0
- package/docs/release-notes/v0.69.0.md +658 -0
- package/docs/release-notes/v0.69.1.md +25 -0
- package/docs/servers.md +44 -5
- package/docs/souls-and-instances.md +11 -7
- package/docs/tui.md +114 -31
- package/docs/upgrading.md +14 -5
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +345 -89
- package/lib/file-pieces.mjs +49 -0
- package/lib/instance-events.mjs +25 -4
- package/lib/launch-prompt-fixtures/README.md +62 -0
- package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
- package/lib/launch-prompt-fixtures.mjs +49 -0
- package/lib/launch-prompt-resume.mjs +55 -0
- package/lib/login-environment.mjs +27 -9
- package/lib/schedule.mjs +3 -3
- package/lib/servers.mjs +117 -23
- package/lib/session-end.mjs +82 -0
- package/lib/session-input.mjs +43 -9
- package/lib/session-resume-contract.mjs +32 -0
- package/lib/session-resume.mjs +310 -0
- package/lib/session-seen.mjs +163 -0
- package/lib/session-viewer.mjs +147 -44
- package/lib/soul-composition.mjs +2 -1
- package/lib/start-env.mjs +110 -0
- package/lib/tmux-server-scope.mjs +139 -14
- package/lib/workspace.mjs +38 -4
- package/package-catalog.json +10 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -0
- package/packages/client/cli-locator.mjs +3 -2
- package/packages/client/deployment-data.mjs +7 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/file-output-exec.mjs +98 -0
- package/packages/client/instance-display-name.mjs +18 -0
- package/packages/client/launch-prompt-outcome.mjs +25 -13
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/session-attach.mjs +35 -5
- package/packages/client/session-resume-cli.mjs +64 -0
- package/packages/client/session-resume-trigger.mjs +167 -0
- package/packages/client/session-resume.mjs +332 -0
- package/packages/client/tmux-status.mjs +30 -7
- package/packages/client/waiting-on-you.mjs +11 -4
- package/packages/client/workspace-step.mjs +17 -5
- package/packages/record/lib/last-conversation.mjs +123 -0
- package/packages/record/lib/session-roots.mjs +10 -1
- package/packages/tui/README.md +1 -1
- package/packages/tui/lib/client.mjs +2 -1
- package/packages/tui/lib/main.mjs +5 -3
- package/packages/tui/lib/model.mjs +57 -15
- package/packages/tui/lib/store.mjs +8 -7
- package/packages/tui/lib/term/text.mjs +12 -9
- package/packages/tui/lib/views/capabilities.mjs +6 -6
- package/packages/tui/lib/views/frame.mjs +72 -7
- package/packages/tui/lib/views/help.mjs +9 -4
- package/packages/tui/lib/views/instances.mjs +46 -29
- package/packages/tui/lib/views/souls.mjs +9 -8
- 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.
|
|
62
|
-
|
|
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
|
-
|
|
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
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
each tick,
|
|
146
|
-
|
|
147
|
-
|
|
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
|
|
165
|
-
part of it: the service can end, stop or restart, and the
|
|
166
|
-
agents go on. The scope ends when
|
|
167
|
-
removes it then. That is usually the
|
|
168
|
-
support the panes are in the scope too
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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
|
-
|
|
192
|
-
|
|
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
|
|
571
|
-
`OATS_TEST_SYSTEM_TOOL_DIRS` (test seams of the server's
|
|
572
|
-
[own
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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,
|
|
1086
|
-
malformed or
|
|
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
|
|
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
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
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,
|
|
1187
|
-
|
|
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
|
|
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
|
|
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,
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
|
|
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:
|