@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
@@ -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 uses the saved
47
- briefing and state in a new harness conversation; it does not resume an old
48
- harness conversation ID. Once the kernel accepts the start or restart, the
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 **Keyboard
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 stop at the ends ("No workspace above this one." /
289
- "No workspace below this one."). Each is a pick, so walking the list with
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, after its usual
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 instance's menu and its panel.
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
- actions menu and in the context panel, which runs that command for that row after a confirmation.
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, wheel up first
790
- (the pane scrolls back through tmux's history), then select. The wheel scrolls
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 first for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
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. |