@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.
- package/bin/oats.mjs +180 -36
- package/docs/capabilities.md +73 -10
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/configuration.md +68 -2
- package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
- package/docs/design/2026-10-22-module-upgrade.md +1 -1
- package/docs/desktop-cli-api.md +600 -25
- package/docs/desktop-instance-start.md +59 -3
- package/docs/desktop.md +175 -10
- package/docs/execution-targets.md +536 -62
- package/docs/harness-trust.md +3 -1
- package/docs/implementation.md +33 -15
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +25 -16
- package/docs/oats-local.schema.json +2 -2
- package/docs/official-catalog.md +6 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.69.0.md +658 -0
- package/docs/release-notes/v0.69.1.md +25 -0
- package/docs/release-notes/v0.69.2.md +259 -0
- package/docs/servers.md +51 -7
- package/docs/soul.schema.json +1 -0
- package/docs/souls-and-instances.md +46 -9
- package/docs/tui.md +177 -21
- package/docs/upgrading.md +16 -7
- package/docs/workspaces.md +2 -2
- package/injects/instance-boundary.md +19 -33
- package/injects/work-attached.md +8 -13
- package/injects/work-checkout.md +16 -30
- package/injects/work-directory.md +9 -15
- package/injects/work-workspace.md +8 -19
- package/injects/work-worktree.md +18 -33
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +496 -127
- package/lib/file-pieces.mjs +49 -0
- package/lib/instance-background.mjs +54 -0
- package/lib/instance-events.mjs +25 -4
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +35 -0
- package/lib/instance-resolution.mjs +3 -2
- package/lib/instance-same-work.mjs +67 -0
- package/lib/instance-upgrade.mjs +18 -0
- 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/materialize.mjs +23 -2
- package/lib/resolve.mjs +32 -5
- package/lib/schedule.mjs +3 -3
- package/lib/servers.mjs +136 -27
- package/lib/session-end.mjs +82 -0
- package/lib/session-input.mjs +43 -9
- package/lib/session-resume-contract.mjs +33 -0
- package/lib/session-resume.mjs +337 -0
- package/lib/session-seen.mjs +163 -0
- package/lib/session-viewer.mjs +147 -44
- package/lib/soul-composition.mjs +15 -11
- package/lib/start-env.mjs +110 -0
- package/lib/tmux-server-scope.mjs +139 -14
- package/lib/workspace.mjs +41 -6
- package/package-catalog.json +11 -5
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +39 -8
- package/packages/client/cli-locator.mjs +3 -2
- package/packages/client/deployment-data.mjs +16 -0
- package/packages/client/deployment-panel.mjs +7 -0
- package/packages/client/file-output-exec.mjs +98 -0
- package/packages/client/instance-tree.mjs +64 -14
- package/packages/client/launch-prompt-outcome.mjs +25 -13
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/panel-views.mjs +11 -3
- package/packages/client/remote-roster.mjs +5 -1
- package/packages/client/roster-sections.mjs +50 -6
- package/packages/client/same-work.mjs +49 -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/soul-rows.mjs +2 -0
- package/packages/client/spawn-apply-contract.mjs +2 -1
- package/packages/client/spawn-decision.mjs +4 -1
- package/packages/client/spawn-preview-contract.mjs +12 -1
- package/packages/client/spawn-preview.mjs +2 -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 +2 -2
- package/packages/tui/lib/client.mjs +7 -3
- package/packages/tui/lib/main.mjs +49 -14
- package/packages/tui/lib/model.mjs +146 -55
- package/packages/tui/lib/store.mjs +84 -27
- package/packages/tui/lib/term/text.mjs +12 -9
- package/packages/tui/lib/views/frame.mjs +74 -7
- package/packages/tui/lib/views/help.mjs +10 -3
- package/packages/tui/lib/views/instances.mjs +41 -3
- package/skills/oats-getting-started/SKILL.md +117 -4
|
@@ -43,9 +43,12 @@ entry, or falls back to the recorded launch when it is no longer offered.
|
|
|
43
43
|
|
|
44
44
|
Enter a model or leave the field blank to use the selected launch's default.
|
|
45
45
|
An old harness's model is not carried to a different harness. Available local model
|
|
46
|
-
suggestions are advisory; a model ID can also be typed. Start
|
|
47
|
-
|
|
48
|
-
|
|
46
|
+
suggestions are advisory; a model ID can also be typed. Start opens a fresh
|
|
47
|
+
harness conversation on the saved briefing and state. The one exception is a
|
|
48
|
+
resume after a shutdown, a reboot or a crash, which continues the instance's
|
|
49
|
+
own last conversation ([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown));
|
|
50
|
+
it replaces the earlier rule that no start resumes a conversation (OATS 0.69).
|
|
51
|
+
A Start or Restart from this dialog is never a resume. Once the kernel accepts the start or restart, the
|
|
49
52
|
dialog closes and Desktop opens the instance's terminal as soon as its row is
|
|
50
53
|
running with a terminal session, so whatever the harness shows first (a
|
|
51
54
|
confirmation such as Claude Code's development-channels prompt, an error, the
|
|
@@ -238,3 +241,56 @@ child remains running; a fallback shell or dead pane is stopped. Errors that
|
|
|
238
241
|
prevent a reliable observation remain unknown. A row that records a Herdr
|
|
239
242
|
target (Herdr was removed in 0.31.0) is never observed: it shows the kernel's
|
|
240
243
|
`E_HERDR_REMOVED` text, and Open and Start are disabled.
|
|
244
|
+
|
|
245
|
+
## When Desktop opens
|
|
246
|
+
|
|
247
|
+
After a shutdown, a reboot or a crash, the instances that were running have
|
|
248
|
+
lost their sessions. OATS Desktop asks the kernel to resume them: it runs
|
|
249
|
+
`oats session resume --json`
|
|
250
|
+
([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown)), and
|
|
251
|
+
the kernel does the rest. The kernel looks
|
|
252
|
+
at every deployment on this computer's list (local deployments only, never a
|
|
253
|
+
server's) and resumes each lost session as it decides. What the kernel does to
|
|
254
|
+
a session, when it starts one fresh from its briefing instead, and when it
|
|
255
|
+
stops trying for one that keeps losing its session, is the kernel's rule,
|
|
256
|
+
written beside the command. A session lost long ago is not resumed
|
|
257
|
+
automatically, and Desktop says nothing about it; `oats session start
|
|
258
|
+
--resume` still brings it back by hand. Desktop owns no session: it runs the
|
|
259
|
+
command and shows nothing of its answer. There is no switch to turn it off.
|
|
260
|
+
|
|
261
|
+
**When it runs.** Once when Desktop opens, after Desktop has imported its
|
|
262
|
+
saved workspaces into this computer's deployments list, because the sweep
|
|
263
|
+
reads that list. After that, whenever Desktop reads a roster that shows an
|
|
264
|
+
instance of a local deployment, as the roster names its deployments, whose
|
|
265
|
+
session was lost and that is not running, and only then:
|
|
266
|
+
|
|
267
|
+
- at most one sweep at a time, and at least 30 seconds after the last one
|
|
268
|
+
started (the one at launch counts);
|
|
269
|
+
- after a sweep that a status read started, every instance it was started
|
|
270
|
+
for waits until it changes (it runs, or it is no longer lost); so does an
|
|
271
|
+
instance any sweep could not resume, found was not lost, or left because it
|
|
272
|
+
was lost long ago. Such an instance does not set off another sweep until a
|
|
273
|
+
later roster shows it running or no longer lost, or a sweep resumes it;
|
|
274
|
+
- never for another machine's instances.
|
|
275
|
+
|
|
276
|
+
There is no timer and no queue: a read that comes too soon starts nothing,
|
|
277
|
+
and the next read asks again. A new window, a workspace switch, a restarted
|
|
278
|
+
backend or Desktop coming to the front start nothing on their own. The rule
|
|
279
|
+
is shared with the TUI (`packages/client/session-resume-trigger.mjs`), and
|
|
280
|
+
the kernel's machine lock and its record of this boot make running it from
|
|
281
|
+
several clients safe. It runs only when the installed OATS CLI advertises the
|
|
282
|
+
`session-resume` feature. Without it, nothing runs and nothing is said.
|
|
283
|
+
|
|
284
|
+
**Nothing is shown.** Desktop says nothing about a sweep: no notice, whatever
|
|
285
|
+
it resumed, started fresh, left waiting for you or could not resume (the
|
|
286
|
+
product owner, 2026-10-27). A resumed instance shows running in the roster
|
|
287
|
+
once a read sees it running. A sweep that fails writes one line with its code
|
|
288
|
+
to Desktop's log. `oats tui` says nothing about a sweep either
|
|
289
|
+
([Resuming lost sessions](tui.md#resuming-lost-sessions)).
|
|
290
|
+
|
|
291
|
+
**Quitting does not stop a sweep.** The sweep runs in a process session of its
|
|
292
|
+
own, and writes its answer to files rather than to Desktop. Quitting Desktop,
|
|
293
|
+
or Desktop crashing, while it runs leaves it to finish.
|
|
294
|
+
|
|
295
|
+
How the clients run the command and read its answer is in
|
|
296
|
+
[desktop-cli-api.md](desktop-cli-api.md#how-the-clients-run-the-sweep).
|
package/docs/desktop.md
CHANGED
|
@@ -191,6 +191,18 @@ workspace on a server: `name — server`).
|
|
|
191
191
|
window they were opened in, and switching that window back to the
|
|
192
192
|
workspace brings them back. A window whose workspace another window takes
|
|
193
193
|
over closes its tabs of that workspace.
|
|
194
|
+
- Switching back also puts the keyboard back where you left it in that
|
|
195
|
+
workspace, with no click: in the terminal you were typing in, ready to
|
|
196
|
+
type; on the instance's row in the list of instances, once that list is
|
|
197
|
+
read; on the tab, or the control of the page or the views you were on. Going
|
|
198
|
+
to the list of workspaces to pick one doesn't move that place: the
|
|
199
|
+
terminal you typed in before is still where the focus comes back. If that
|
|
200
|
+
tab closed while the workspace was hidden, the focus goes to the tab active
|
|
201
|
+
in its place, or to the page when no tab is left. An instance retired
|
|
202
|
+
elsewhere keeps its tab until the workspace's list of instances is read
|
|
203
|
+
again: the focus goes into that tab, and when it closes, to the next tab. A
|
|
204
|
+
stopped instance's tab ("session ended") gets the focus, and nothing typed
|
|
205
|
+
there reaches a terminal.
|
|
194
206
|
- A tab's terminal ends ("session ended") when its instance's tmux window
|
|
195
207
|
goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
|
|
196
208
|
another instance's terminal. Stopping an instance leaves its tab open.
|
|
@@ -213,8 +225,8 @@ foot, one bar: the OATS mark and the sidebar toggle (**Hide the sidebar**)
|
|
|
213
225
|
after it, and at the bar's right **Spawn instance**, its words alone (a ground
|
|
214
226
|
only on hover), which
|
|
215
227
|
opens Quick Open (⌘P / Alt+P, named in its tooltip) to pick a soul and then
|
|
216
|
-
the spawn dialog, and the settings cog, whose menu holds **Theme…** and
|
|
217
|
-
shortcuts…**, each with its shortcut. A window opens on the **Workspace
|
|
228
|
+
the spawn dialog, and the settings cog, whose menu holds **Theme…**, **Font…** and
|
|
229
|
+
**Keyboard shortcuts…**, each with its shortcut when it has one. A window opens on the **Workspace
|
|
218
230
|
overview** page, on its **Souls** tab: at launch, and after you choose a
|
|
219
231
|
workspace for it. Connections is in the command palette
|
|
220
232
|
(**Settings: Connections…**), and the palette opens with its shortcut or
|
|
@@ -236,6 +248,53 @@ hidden; a window too narrow for it shows it narrower, and gives it back when
|
|
|
236
248
|
the window grows again. The terminals refit as it moves, and their programs
|
|
237
249
|
hear the new size once, when you let go.
|
|
238
250
|
|
|
251
|
+
**Theme and font.** The settings cog's **Theme…**, the palette's **Theme: choose…** and
|
|
252
|
+
⇧⌘Space / Ctrl+Shift+Space open the theme picker (White, Solarized, Dark, or
|
|
253
|
+
This computer, which follows the computer's own theme). The font has a picker
|
|
254
|
+
of its own, the settings cog's **Font…** or **Font: choose…** in the palette (no
|
|
255
|
+
shortcut unless you give it one in the shortcuts editor), with two choices:
|
|
256
|
+
|
|
257
|
+
- **Omarchy's font**, the default on a computer that runs Omarchy. On Linux the whole window and its
|
|
258
|
+
terminals use the computer's monospace font, the one `omarchy font current`
|
|
259
|
+
names and `omarchy font set` changes (fontconfig's `monospace`, on any
|
|
260
|
+
Linux). A font changed that way shows when Desktop next starts, at the
|
|
261
|
+
latest. On Windows it is the system's monospace font, for the window and the
|
|
262
|
+
terminals. On macOS the choice is named **JetBrains Mono**, Omarchy's default
|
|
263
|
+
face: the window uses it (or the system's monospace font where it is not
|
|
264
|
+
installed), and the terminals keep Inconsolata. On every platform, instance
|
|
265
|
+
names in the sidebar and on tabs are a little smaller in it (12px, from
|
|
266
|
+
12.5px), since a monospace face runs wider.
|
|
267
|
+
- **System font**, the faces Desktop had before: the system's interface font
|
|
268
|
+
for the window and Inconsolata in the terminals. It is the default on every
|
|
269
|
+
computer that doesn't run Omarchy (other Linux, macOS and Windows).
|
|
270
|
+
|
|
271
|
+
Desktop knows a computer runs Omarchy when Omarchy's theme directory
|
|
272
|
+
(`~/.local/state/omarchy/current`) is there, the same one the **This computer**
|
|
273
|
+
theme reads. A font you chose always wins over the default.
|
|
274
|
+
|
|
275
|
+
The terminal's size belongs to the face its terminals are in, since the same
|
|
276
|
+
size looks larger in a wider face. Omarchy's font in the terminals defaults to
|
|
277
|
+
13px (JetBrains Mono, Omarchy's default face, at 13px), and Inconsolata, with
|
|
278
|
+
System font, on macOS or when Omarchy's font shows System font's faces, to
|
|
279
|
+
15px, on every computer. A size you set is kept for that face only, and a
|
|
280
|
+
font change never carries it to the other. Resetting the size or the zoom
|
|
281
|
+
goes back to the default of the face in use.
|
|
282
|
+
|
|
283
|
+
The computer's monospace font is used only once it draws at a fixed width.
|
|
284
|
+
Desktop checks it at start and on each choice in the picker. Where the
|
|
285
|
+
computer has no monospace font, or `monospace` names a bitmap font (which the
|
|
286
|
+
window cannot draw), **Omarchy's font** shows System font's faces, and its row
|
|
287
|
+
in the picker says **No monospace font on this computer: showing System
|
|
288
|
+
font**. The choice stays Omarchy's font, so the computer's font is used once
|
|
289
|
+
it draws.
|
|
290
|
+
|
|
291
|
+
The choice is kept on this computer, like the theme, and applies at once:
|
|
292
|
+
open terminals switch font and take that face's size in place, and keep what
|
|
293
|
+
they show. Settings → Terminal shows the size and the default of the face in
|
|
294
|
+
use. A terminal font family set with the palette's **Terminal: set font
|
|
295
|
+
family…** still wins until **Terminal: reset typography**, and the size stays
|
|
296
|
+
the one of the font chosen underneath it.
|
|
297
|
+
|
|
239
298
|
The list of workspaces is always shown. Its heading holds **Add local
|
|
240
299
|
workspace…** (the **+**). The list has one row per workspace this window can show, whatever
|
|
241
300
|
machine it is on: every workspace the Desktop serves, those only on servers
|
|
@@ -285,8 +344,9 @@ computer.
|
|
|
285
344
|
in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
|
|
286
345
|
selection; one another window shows moves here ([A workspace another window
|
|
287
346
|
shows](#a-workspace-another-window-shows)). The leader's ↑ / ↓ go to the
|
|
288
|
-
previous / next row, and
|
|
289
|
-
|
|
347
|
+
previous / next row, and wrap: past the last row comes the first, and
|
|
348
|
+
before the first the last. With no other workspace to show, nothing moves
|
|
349
|
+
and one line says "No other workspace to show." Each is a pick, so walking the list with
|
|
290
350
|
them moves every workspace it passes that another window shows into this
|
|
291
351
|
window.
|
|
292
352
|
- **Open in new window** is in a row's context menu (a right-click, or
|
|
@@ -544,7 +604,8 @@ roster row reads **Retiring…** while:
|
|
|
544
604
|
changed, runs nothing, and the row reads as the roster says at once.
|
|
545
605
|
|
|
546
606
|
A retiring row offers no Start, Stop, Restart or Open, and no inline
|
|
547
|
-
button. **Retire instance…** stays in the row's menu,
|
|
607
|
+
button. **Retire instance…** stays in the row's context menu (right-click,
|
|
608
|
+
Shift+F10 or the ContextMenu key), after its usual
|
|
548
609
|
confirmation: OATS refuses a second retire while one runs, and when the
|
|
549
610
|
holder can't be read it may be the only way on.
|
|
550
611
|
|
|
@@ -589,7 +650,7 @@ heading. The tab you chose is
|
|
|
589
650
|
is disabled, and says why, when that soul can't be told or shown exactly:
|
|
590
651
|
the instance records none, it is no longer among the deployment's souls,
|
|
591
652
|
several match, another soul of the deployment has the same name, or the
|
|
592
|
-
instance is on a deployment other than the one the Workspace page shows. Restart with… stays in the
|
|
653
|
+
instance is on a deployment other than the one the Workspace page shows. Restart with… stays in the row's context menu (right-click, Shift+F10 or the ContextMenu key) and its panel.
|
|
593
654
|
- **Not shown live.** A deployment that can't be shown live says why in a few
|
|
594
655
|
words on its heading ("ssh needs a prompt", "Timed out", "OATS too old to
|
|
595
656
|
report its workspace"), and **How to fix** under it gives the full sentence
|
|
@@ -749,7 +810,7 @@ than showing nothing. A row that can't be opened says why on the row:
|
|
|
749
810
|
Herdr no longer supported, gone from <server>, not reachable on <server>, or <server> not reached.
|
|
750
811
|
For an instance a server no longer lists, the reason names the command that removes it from this
|
|
751
812
|
computer (`oats server forget <server> --instance <name>`), and the row offers **Forget…**, in its
|
|
752
|
-
|
|
813
|
+
context menu (right-click, Shift+F10 or the ContextMenu key) and in the context panel, which runs that command for that row after a confirmation.
|
|
753
814
|
Only this computer's saved route goes; nothing changes on the server, and the roster is read again.
|
|
754
815
|
|
|
755
816
|
## Remote terminals
|
|
@@ -776,6 +837,28 @@ A remote instance's tabs close only when its server answers without it
|
|
|
776
837
|
(retired there, or gone from it), never because the server can't be reached
|
|
777
838
|
or its roster read is out of date.
|
|
778
839
|
|
|
840
|
+
## When an agent waits on you
|
|
841
|
+
|
|
842
|
+
While an instance waits on you (its `waitingOnYou` claim), the sidebar marks
|
|
843
|
+
its row **Needs input**, and each terminal tab that shows it carries a row
|
|
844
|
+
over its terminal:
|
|
845
|
+
|
|
846
|
+
- **Needs input**, then how long it has waited (`· 12 min`), on one line.
|
|
847
|
+
- Under it, the agent's question as it wrote it, shown as plain text. When
|
|
848
|
+
the agent left no text, the row says why in words, for example "Waiting for
|
|
849
|
+
a tool approval". When the agent gave no reason either, the first line
|
|
850
|
+
says it all and the row has no second line.
|
|
851
|
+
- The question wraps to at most three lines, and the row never takes more
|
|
852
|
+
than a quarter of the pane; a longer question ends with "…". The tab's
|
|
853
|
+
tooltip and the sidebar's card have the whole of it. A pane too short
|
|
854
|
+
for even the first line shows no row: the tab's mark still says the
|
|
855
|
+
instance needs input.
|
|
856
|
+
|
|
857
|
+
The terminal gives up exactly the row's height. It resizes only when the wait
|
|
858
|
+
starts, ends or its text changes, never as the age ticks over. In a split,
|
|
859
|
+
each group's row follows its own tab. The row goes as soon as the wait ends,
|
|
860
|
+
and it never shows for a stopped instance or a roster that is out of date.
|
|
861
|
+
|
|
779
862
|
## Copy from a terminal
|
|
780
863
|
|
|
781
864
|
Drag over an agent's output to select it, as in any terminal. The selection
|
|
@@ -786,8 +869,17 @@ With nothing selected, Ctrl+Shift+C, ⌘C and Edit › Copy do nothing and leave
|
|
|
786
869
|
the clipboard as it was, and Ctrl+C still interrupts the program in the pane. Copies trim trailing spaces at line ends, as native
|
|
787
870
|
terminals do.
|
|
788
871
|
|
|
789
|
-
A drag selects what is on the screen. To select older output,
|
|
790
|
-
|
|
872
|
+
A drag selects what is on the screen. To select older output, scroll back
|
|
873
|
+
first, then select. Wheel up, or press **Shift+PgUp**, or **Ctrl+B** then `[`:
|
|
874
|
+
the pane scrolls back through tmux's history, and `q` returns to the bottom.
|
|
875
|
+
Ctrl+B `[` needs tmux 3.3 or later on the computer the agent runs on. On
|
|
876
|
+
another computer, Shift+PgUp and Ctrl+B `[` need OATS 0.69.0 or later there;
|
|
877
|
+
with an older OATS, scroll back with the wheel. Ctrl+B followed by any other
|
|
878
|
+
key still reaches the agent. On Linux and Windows, a shortcut you bind to
|
|
879
|
+
Ctrl+B in the shortcuts window takes Ctrl+B first, if it is one that works in
|
|
880
|
+
a terminal. The pane is shared: while
|
|
881
|
+
you scroll back, anyone else viewing the same agent sees the same paused view
|
|
882
|
+
until you return to the bottom, as with the wheel. The wheel scrolls
|
|
791
883
|
as before, and a program that uses the mouse itself still receives the wheel.
|
|
792
884
|
It no longer receives mouse clicks or drags from the Desktop: those always
|
|
793
885
|
select.
|
|
@@ -829,6 +921,22 @@ right of its parent, and related instances are grouped together. Siblings are
|
|
|
829
921
|
joined by a dotted line through their dots. A parent's line to its children
|
|
830
922
|
runs just to the right of the dotted line, so the two never merge.
|
|
831
923
|
|
|
924
|
+
A parent's line joins only the children that do its work. When the instances'
|
|
925
|
+
OATS has the `instance-same-work` feature, a child the kernel reports as doing
|
|
926
|
+
its parent's work (`sameWork: true` in its row, set with `oats spawn …
|
|
927
|
+
--same-work` or `oats instance same-work <instance> on`) is joined to its
|
|
928
|
+
parent, and any other child keeps its place and its indent with no line to its
|
|
929
|
+
parent. Under one parent the joined children are listed first, then the others,
|
|
930
|
+
each part in name order, so the parent's line ends at its last joined child and
|
|
931
|
+
never passes one it doesn't join. Nothing else marks the flag: no label, no
|
|
932
|
+
tag, and nothing for a screen reader, which still hears each child "under" its
|
|
933
|
+
parent in the command palette. The command palette draws the same lines, in
|
|
934
|
+
its own recency order inside each part. For another machine's instances, its
|
|
935
|
+
host must report the feature too, through an installed OATS with
|
|
936
|
+
`server-probe-features`. A host without the feature, or one whose features are
|
|
937
|
+
not known (its last read failed), keeps a line to every child. A spawn from the
|
|
938
|
+
Desktop never sets the flag.
|
|
939
|
+
|
|
832
940
|
A row shows the instance's name as words: each `-` is a space, and the first
|
|
833
941
|
letter is a capital, so `oats-expert-maintainer-lanes` reads "Oats expert
|
|
834
942
|
maintainer lanes". Only the row's label changes. The hover card, the command
|
|
@@ -853,6 +961,63 @@ how long it has waited. A collapsed parent shows "! N below" on its second
|
|
|
853
961
|
line for the rows it hides that need input, beside its own mark when it waits
|
|
854
962
|
too. Rows never move or grow, and nothing animates.
|
|
855
963
|
|
|
964
|
+
A row has no ⋯ button. Its actions (Open in split, Open pull request…,
|
|
965
|
+
Knowledge & capabilities…, Start…, Restart with…, Stop…, Retire instance…,
|
|
966
|
+
Move to background or out of it ([Background instances](#background-instances)), and
|
|
967
|
+
Forget… for an instance its server no longer lists) are in the row's context
|
|
968
|
+
menu (right-click, Shift+F10 or the ContextMenu key), as a workspace row's are.
|
|
969
|
+
It opens where you right-click, or on the row from the keyboard; the arrow keys,
|
|
970
|
+
Home and End move in it, and Esc or Tab close it with the focus back on the
|
|
971
|
+
row. A right-click never opens the row's terminal. While the menu can't be used
|
|
972
|
+
(the roster is out of date, one of its actions is still running, or the row
|
|
973
|
+
can't be used from this computer), it opens nothing, and one line at the
|
|
974
|
+
bottom of the main area says why, as a leader key that can't act does. The row's own tools stay: its pull request link and, on a
|
|
975
|
+
stopped row, **Start…**.
|
|
976
|
+
|
|
977
|
+
## Background instances
|
|
978
|
+
|
|
979
|
+
An instance can run in the background: it is listed apart, so the main tree
|
|
980
|
+
keeps the agents you work with. Background changes only where an instance is
|
|
981
|
+
listed. It starts, opens, takes input, messages and retires as any other.
|
|
982
|
+
|
|
983
|
+
- **Where it is listed.** Background instances leave the main tree for one
|
|
984
|
+
**Background** heading at the very end of the list, in the machine
|
|
985
|
+
headings' style, with a chevron and the number of instances under it. A
|
|
986
|
+
child of a background instance is listed under it there, whatever its own
|
|
987
|
+
setting, and so is the whole chain below it. A background instance whose
|
|
988
|
+
parent is in the main tree is a top row of the section. Inside, the rows
|
|
989
|
+
form their own tree, with the machine headings when the workspace has two
|
|
990
|
+
or more machines; no line joins a row of the section to a row of the main
|
|
991
|
+
tree. With no background instance there is no heading.
|
|
992
|
+
- **Closed by default.** The section starts closed in every new window. A
|
|
993
|
+
click, Enter or Space on the heading opens or closes it, and the right and
|
|
994
|
+
left arrows open and close it as they do a parent row. It stays as you left
|
|
995
|
+
it while the window shows the workspace, as a parent row's fold does.
|
|
996
|
+
Selecting an instance's tab, or opening one from the command palette, never
|
|
997
|
+
opens it; **Show in roster** and a spawn's **Show its row** do, since they
|
|
998
|
+
ask to see the row. A spawn you run in the background is listed there from
|
|
999
|
+
the start. The command palette lists every instance, background ones
|
|
1000
|
+
included, and the previous and next instance keys pass over the rows of a
|
|
1001
|
+
closed section. When the row you are on moves to a closed section, the
|
|
1002
|
+
focus goes to the heading.
|
|
1003
|
+
- **Needs input.** While an instance of the section waits on you, the
|
|
1004
|
+
heading carries the **Needs input** mark, open or closed. Open, the
|
|
1005
|
+
waiting row shows its own mark, and a folded parent says how many below it
|
|
1006
|
+
wait, as in the main tree. The workspace's Needs input mark counts
|
|
1007
|
+
background instances too.
|
|
1008
|
+
- **Choosing it.** The **Spawn** dialog has a **Run in background** switch,
|
|
1009
|
+
set to the soul's default (`background:` in its `soul.yaml`). A row's
|
|
1010
|
+
context menu offers **Move to background**, or **Move out of background**
|
|
1011
|
+
on a background instance, which runs `oats instance background`. A row
|
|
1012
|
+
that is in the section only because its parent is offers neither: move
|
|
1013
|
+
the parent. The setting is the instance's own, kept in its home by OATS:
|
|
1014
|
+
it lasts through restarts and is not inherited.
|
|
1015
|
+
|
|
1016
|
+
This needs OATS with the `instance-background` feature on this computer,
|
|
1017
|
+
and for an instance on a server, on that server too. With an older OATS the
|
|
1018
|
+
sidebar lists every instance in the main tree, and the switch and the menu
|
|
1019
|
+
items are not shown.
|
|
1020
|
+
|
|
856
1021
|
## An instance's colour
|
|
857
1022
|
|
|
858
1023
|
An instance can have a colour, one of the soul palette's six (Sand, Sage,
|
|
@@ -926,7 +1091,7 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
926
1091
|
| "This Desktop is older than the installed oats CLI" card | The CLI found is a released version above the range this Desktop works with, usually because the CLI was updated first. Install OATS Desktop of the version the card names; the card offers no npm command, since installing the CLI this Desktop pins would downgrade it. Reads and terminals keep working meanwhile; **Choose oats…** points at another, compatible CLI and **Retry** re-probes. |
|
|
927
1092
|
| Spawn disabled, no card | The probe hasn't settled yet (transient, resolves in ms). If it persists, the backend is unreachable — restart the app. |
|
|
928
1093
|
| Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux -L oats ls` (the OATS tmux server, where instances run) and `tmux ls` (your default server, where an instance started by an earlier kernel may still be). |
|
|
929
|
-
| Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: wheel up
|
|
1094
|
+
| Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: scroll back first (wheel up, Shift+PgUp or Ctrl+B then `[`) for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
|
|
930
1095
|
| macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
|
|
931
1096
|
| Log says `server on 4820 — this app's server at version X (this app is Y), not started by this app — left running — starting a dedicated one on 4821` | Another OATS Desktop server holds the default port: another installed version or a dev checkout that is running, or one an earlier Desktop left running. The app serves from the port it names and never stops a server it did not start. From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill). A server left by an earlier Desktop (seen on Linux, where it outlived the app in its own `app-…scope`) must be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`), then restart the app. |
|
|
932
1097
|
| Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use **Add local workspace…** (the **+** at the top of the sidebar) to select the right folder. |
|