@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
package/docs/tui.md CHANGED
@@ -132,7 +132,7 @@ while a terminal is open); under 80 columns it has the whole width.
132
132
  `since …` and its reason on rows of its own; the note of a view of one
133
133
  deployment; and the line that says what happened after an open, an act or
134
134
  a spawn. Then an empty row. A line that goes at the next key and fits one
135
- row (`No workspace above this one.`) stands in that empty row instead, so
135
+ row (`No other workspace to show.`) stands in that empty row instead, so
136
136
  nothing under it moves.
137
137
  - **The views** follow as an accordion, always in this order: `Instances`,
138
138
  `Souls`, `Capabilities`, each with its key dim at the right edge. The open
@@ -178,7 +178,10 @@ while a terminal is open); under 80 columns it has the whole width.
178
178
  order, from the same code. It is in name order, by each group's top
179
179
  instance, so starting or stopping an instance moves nothing. An instance
180
180
  that others were spawned from has them indented under it, and keeps its
181
- place when it gains or loses one. An empty row stands between each run
181
+ place when it gains or loses one. Under one parent, the instances that do
182
+ its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
183
+ come first, then the others, each part in name order, as the Desktop lists
184
+ them. An empty row stands between each run
182
185
  of instances related to no other and the group before or after it. The
183
186
  indent alone says which instance is under which: no mark is drawn for
184
187
  it. A row whose instances are folded away (`h`) says how many after its
@@ -237,6 +240,27 @@ while a terminal is open); under 80 columns it has the whole width.
237
240
  own deployment, and a name that is no instance there, or two of them, is
238
241
  not shown. From 80 columns up it stands beside the sidebar; on a narrower
239
242
  terminal `Tab` opens it as a page over the whole screen.
243
+ - **Background instances** ([#1579](https://github.com/awebai/oats/issues/1579))
244
+ are listed apart, as in the Desktop's sidebar. An instance whose
245
+ `background` is on (`oats instance background`, or its soul's default at
246
+ spawn) leaves the list, and so do the instances below it, whatever their
247
+ own setting. They stand under one heading at the very end of the list:
248
+ `▸ Background 3` (`>` in ASCII), the word in bold and the count dim. The
249
+ heading starts closed in every run, and stays as you leave it for each
250
+ workspace while the TUI runs. It can be selected: `Enter` or `Space`
251
+ opens or closes it, `Right` opens it (on an open one, goes to its first
252
+ row) and `Left` closes it. Open (`▾`), its rows form their own tree, with
253
+ the deployments' headings in a view of two or more; a background instance
254
+ whose parent is in the list above is a top row there. While one of its
255
+ instances needs input, open or closed, the heading carries `Needs input`
256
+ at its right edge in the roll-up's look (only the `!` on a narrow row),
257
+ and the help's count of instances that need input counts it. A filter
258
+ shows the matching background rows with the section open, without
259
+ changing whether it is kept open, and the heading then counts the
260
+ matches. The movement keys pass over the rows of a closed section, and
261
+ showing a background instance's terminal from the palette leaves the
262
+ section as it was. The palette lists every instance. Without OATS's
263
+ `instance-background` feature every instance stays in the list.
240
264
  - **Opening an agent.** `Enter` on an instance that runs opens its terminal
241
265
  beside the sidebar, where the detail was, as a tab: see
242
266
  [Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
@@ -302,7 +326,7 @@ in its workspace for the rest of the run, also while it is not reached.
302
326
  | `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
303
327
  | `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
304
328
  | `+n` | `+n` | after a name: n instances folded away below it |
305
- | `!` | `!` | needs input: in place of the state mark, in yellow and reverse video (not reversed on the selected row) |
329
+ | `!` | `!` | needs input: in place of the state mark, in yellow and reverse video (not reversed on the selected row); with its terminal shown, the [waiting row](#tabs) under the tab bar says what it waits on |
306
330
  | `N below` | `N below` | N instances folded away below it need input: a tag in reverse video at the row's right edge, `N` where the whole name does not fit beside the words |
307
331
  | `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
308
332
  | `*` | `*` | in the switcher: the workspace that is open |
@@ -473,9 +497,39 @@ fit; the detail shows them whole. The TUI's own words end the same way:
473
497
  reason holds it (an instance gone from its machine, say). An agent on another machine is asked first whether it
474
498
  can be opened (`Esc` gives that up); a machine whose OATS cannot open its
475
499
  sessions is said then.
476
- - **No scrollback but the viewer's own, and no mouse.** The panel shows
477
- what the agent's window shows now; what has scrolled away is reached as
478
- the agent's own terminal reaches it.
500
+ - **The viewer's scroll keys, and no mouse.** The panel shows what the
501
+ agent's window shows now. What has scrolled away is reached through the
502
+ viewer's own keys, as in `oats session attach`: `Shift+PageUp`, or
503
+ `Ctrl+B` then `[`, put it in tmux's copy mode. Then `PageUp`, `PageDown`,
504
+ the arrows, `Ctrl+U` and `Ctrl+D` move, and `q` or `Esc` leaves. The TUI
505
+ adds no key of its own: they reach the viewer as a terminal without the
506
+ kitty keyboard protocol sends them (re-encoded under it), and the viewer
507
+ shows no status line of its own (`--no-status-line`, where the kernel has
508
+ it).
509
+ - **The cheat sheet names them** while a terminal has the focus, and so
510
+ does a zoomed terminal's title row where it has room: `Shift+PageUp or
511
+ Ctrl+B [`, then `scroll back`. Where the row holds one key, `Ctrl+B [`.
512
+ The title row gives them up first: in the Alt family, whose chords lead
513
+ that row, a zoomed terminal 120 columns wide or less does not name
514
+ them. The help does.
515
+ - **As the tab's host says.** Each tab runs its host's viewer, so the
516
+ keys named are the ones that host's kernel says its viewer takes: this
517
+ machine's `oats version --json` for a tab of this machine, the roster's
518
+ probe of its server for another's
519
+ ([`session-attach-prefix-scroll`](desktop-cli-api.md#features)).
520
+ `Shift+PageUp` where the host's kernel lists the feature, and
521
+ `Ctrl+B [` too where its `sessionViewer.prefixScroll` is true (a tmux of
522
+ 3.3 or later, see
523
+ [Inspect, input and attach](execution-targets.md#inspect-input-and-attach)).
524
+ A host whose kernel does not list it, or one the roster did not reach,
525
+ gets no scroll keys named at all: an older viewer may hand
526
+ `Shift+PageUp` to the agent.
527
+ - **A leader of `Ctrl+B`** (`open.detachKey: "C-b"` in
528
+ [`tui.json`](#change-the-keys-tuijson)) takes `Ctrl+B` before the
529
+ viewer reads it, so `Ctrl+B [` cannot be typed there. The sheet and the
530
+ help name `Shift+PageUp` alone.
531
+ - Copy mode is the agent's pane's: while a tab is scrolled back, every
532
+ other viewer of that agent shows the same frozen screen.
479
533
  - **How it works.** The terminal is the kernel's own viewer,
480
534
  `oats session attach`, run in a pane of a tmux server private to this run
481
535
  of `oats tui`: its socket is in a directory of the run's own (mode 0700,
@@ -551,6 +605,37 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
551
605
  of the row with their dividers (they stay open). The shown tab's name
552
606
  stays whole while the row can hold it, and is cut last.
553
607
  - The TUI takes no mouse input: a tab is shown with the keys below.
608
+ - **The waiting row.** While the shown tab's agent waits on you (a live
609
+ `waitingOnYou` claim, as the list's `!` mark shows it), a row
610
+ stands under its group's tab bar, and the agent's screen starts under it:
611
+
612
+ ```
613
+ │[steward 1]│ backend-lead 2
614
+ │ Needs input · 12 min Survey done: yes/no on bumping Claude Code
615
+ │ 2.1.309 + Codex 0.164.0 and removing their old mise installs
616
+ │>
617
+ ```
618
+
619
+ - It reads `Needs input` in the list's needs-input look (reverse video in
620
+ the waiting colour), then how long the agent has waited, dim, after ` · `
621
+ (` - ` in ASCII), then the claim's message, the agent's own text. The
622
+ age comes first, so a cut never removes it.
623
+ - **A claim with no message** says what it waits on in the TUI's words:
624
+ `waiting on a permission prompt`, `asked you a question`,
625
+ `asked for your attention`, or `waiting for your input` when the
626
+ reason is not one of those.
627
+ - **A long message wraps** to at most 3 rows, and to no more than a
628
+ quarter of the group's height; when more is left, the last row ends in
629
+ `…` (`...` in ASCII). The whole message is in the agent's
630
+ [detail](#what-it-shows), and in `oats status`.
631
+ - **The agent's screen loses those rows** while the row stands, so its
632
+ pane is resized when the claim starts, clears or its text changes, and
633
+ never as the age grows: the rows are counted as if the age were its
634
+ longest, `under a minute`.
635
+ - In a [split](#splits) each group has its own row for its own shown tab.
636
+ A hidden tab's claim adds no row: the list's `!` mark shows it.
637
+ - Under `NO_COLOR` the words carry it: `Needs input` stays in reverse
638
+ video.
554
639
  - **Opening.** `Enter` on a row, an instance in
555
640
  [the palette](#the-palette), `Alt+Shift+Up` or `Alt+Shift+Down`, and a
556
641
  [spawn](#spawning-an-agent)'s new agent open a terminal the same way:
@@ -932,10 +1017,12 @@ workspace the list is its row.
932
1017
  - **The leader then `Up` or `Down`**, or the [chords](#chords) `Alt+Up` and
933
1018
  `Alt+Down` (in the Alt family and on macOS; the Ctrl+Alt and Ctrl+Shift
934
1019
  families leave them to the programs, and the leader does it), opens the
935
- workspace before or after the open one, as the list draws them. It does not wrap: at an end nothing
936
- moves, and the line under the list says `No workspace above this one.` or
937
- `No workspace below this one.` until the next key, of any kind (one typed
938
- to an agent too), or a resize. The line stands in the empty row under the
1020
+ workspace before or after the open one, as the list draws them. It wraps,
1021
+ as the [OATS Desktop](desktop.md#workspaces)'s do: `Down` on the last row
1022
+ opens the first, and `Up` on the first opens the last. With no other row
1023
+ to open, nothing moves, and the line under the list says `No other
1024
+ workspace to show.` until the next key, of any kind (one typed to an agent
1025
+ too), or a resize. The line stands in the empty row under the
939
1026
  list, so the list of instances does not move while it shows; only when
940
1027
  that list fills the sidebar, which then has no such row, does the line
941
1028
  take a row, the list giving up its last. With the list's focus (`w`) the
@@ -955,7 +1042,8 @@ workspace the list is its row.
955
1042
  workspace's name is underlined until `Enter` opens another; the list of
956
1043
  instances keeps its selection in reverse video, without its `>`. `Up`/`k`,
957
1044
  `Down`/`j`, `g`/`Home` and `G`/`End` move the cursor over the rows that
958
- open; `Enter` opens its row and gives the list of instances the focus;
1045
+ open, and stop at the list's ends (they do not wrap, as the Desktop
1046
+ list's own do not); `Enter` opens its row and gives the list of instances the focus;
959
1047
  `Esc` gives that focus back with nothing opened; `w` again opens the
960
1048
  switcher, for what the list does not hold. Any other key gives the list
961
1049
  of instances the focus, then does what it does there. The cheat sheet
@@ -1208,6 +1296,63 @@ The exit status never depends on it.
1208
1296
  there can leave `.oats-stop-pending.json` in the agent's home, and then
1209
1297
  the agent can be started but not stopped while that file exists.
1210
1298
 
1299
+ ## Resuming lost sessions
1300
+
1301
+ After a shutdown, a reboot or a crash, the instances that were running have
1302
+ lost their sessions. When `oats tui` opens, it asks the kernel to resume
1303
+ them: it runs `oats session resume --json`, and the kernel does the rest.
1304
+ The kernel looks at every deployment on this computer's list (local
1305
+ deployments only, never another machine's) and resumes each lost session as
1306
+ it decides. What it does to a session, when it starts one fresh from its
1307
+ briefing instead, and when it stops trying for one that keeps losing its
1308
+ session, is the kernel's rule, written beside the command. A session lost
1309
+ long ago is not resumed automatically; `oats session start --resume` still
1310
+ brings it back by hand. `oats tui` owns no session: it runs the command, and
1311
+ says nothing about it.
1312
+
1313
+ **When it runs.** Once the run has started, whether it started in a
1314
+ deployment or in [the switcher](#the-switcher): after the deployment it
1315
+ started in has been added to this computer's list (the sweep reads that
1316
+ list), and without holding up the first frame or the first read. Then
1317
+ again whenever a read of a deployment open in the run shows an instance of
1318
+ this computer whose session was lost and that is not running (another
1319
+ machine's instances shown in the same workspace never count). Never two at
1320
+ a time, and never sooner than 30 seconds after the last one began. After a
1321
+ sweep that a read started, every instance it was started for waits until it
1322
+ changes (it runs, or it is no longer lost); so does an instance any sweep
1323
+ could not resume, found was not lost, or left because it was lost long ago.
1324
+ Such an instance sets off no sweep until a later read shows it running or no
1325
+ longer lost, or a sweep resumes it. There
1326
+ is no timer and no queue: a read that comes too soon starts nothing, and the
1327
+ next read asks again. The rule is the shared client's
1328
+ (`packages/client/session-resume-trigger.mjs`). It runs only when the kernel
1329
+ advertises the `session-resume` feature; without it, nothing runs.
1330
+
1331
+ **What it says.** Nothing. `oats tui` says nothing about a resume: no line
1332
+ when the sweep resumed an instance, started one fresh, left one waiting for
1333
+ you or could not resume one, none when the sweep failed or another sweep
1334
+ held the machine, and none after leaving. The list shows each instance as
1335
+ it is after the next read: after a sweep that ran, the list is read at
1336
+ once, so a resumed instance shows running, and one the sweep did not resume
1337
+ shows not running. To see what a sweep would do, run
1338
+ `oats session resume --plan --json`; `oats session resume` run by hand says
1339
+ what it did, and why it could not resume an instance.
1340
+
1341
+ **There is no setting to turn it off.** To keep an instance down, stop it
1342
+ with OATS (`X`, or `oats instance stop`): a stopped instance is not lost,
1343
+ and the sweep leaves it alone.
1344
+
1345
+ **Quitting does not stop a sweep.** It is a change, like an act you
1346
+ confirmed ([above](#stopping-starting-restarting-and-retiring)): it runs in
1347
+ a session of its own, writes its answer to files of its own, and is never
1348
+ signalled by `oats tui`. Quitting while it runs leaves it to finish, without
1349
+ a word: unlike an act, a sweep still running is not named after the screen
1350
+ is left.
1351
+
1352
+ `S` and `R` are unchanged: a start or restart from `oats tui` starts the
1353
+ instance as it was last launched, and never resumes a conversation. Only
1354
+ the sweep resumes.
1355
+
1211
1356
  ## Spawning an agent
1212
1357
 
1213
1358
  `n` spawns an agent of a soul of the open workspace, on this machine, with
@@ -1550,8 +1695,9 @@ from every focus, an agent's terminal included: the agent never gets them.
1550
1695
  | `Up` `k`, `Down` `j` | move the selection; with the detail focused, scroll it |
1551
1696
  | `g` `Home`, `G` `End` | first row, last row |
1552
1697
  | `PageUp`, `PageDown` | one page |
1553
- | `Left` `h` | fold the instances below the row away; on a row with none, or already folded, go to its parent |
1554
- | `Right` `l` | show them again; on a row already open, go to its first child |
1698
+ | `Left` `h` | fold the instances below the row away; on a row with none, or already folded, go to its parent (from a top row of the Background section, its heading); on the Background heading, close it |
1699
+ | `Right` `l` | show them again; on a row already open, go to its first child; on the Background heading, open it, or go to its first row |
1700
+ | `Enter`, `Space` | on the Background heading, open or close it |
1555
1701
  | `Tab` | move between the list and the detail; under 80 columns, open and close the detail page |
1556
1702
  | `/` | filter |
1557
1703
  | `r` | read now |
@@ -1580,8 +1726,8 @@ from every focus, an agent's terminal included: the agent never gets them.
1580
1726
  | `Ctrl+Z` | suspends: the shell gets the terminal back as it was; `fg` returns, redraws and reads at once |
1581
1727
  | `Ctrl+L` | redraws the whole screen, and sets the terminal's modes again if something reset them |
1582
1728
 
1583
- The selection stands on instances only, and in the switcher on its rows: a
1584
- heading, a reason and a note are passed over. What stands above the first
1729
+ The selection stands on instances and the Background heading only, and in
1730
+ the switcher on its rows: any other heading, a reason and a note are passed over. What stands above the first
1585
1731
  instance or under the last one comes into view with it. When a movement key
1586
1732
  has no instance to go to (the selection is on the first or the last one, or
1587
1733
  the list has none), it scrolls the list instead, so the rows after the last
@@ -1619,7 +1765,7 @@ which edits the command line in your editor, is `Ctrl+X` twice, then
1619
1765
  |---|---|
1620
1766
  | `k` or `Space` | opens [the palette](#the-palette) |
1621
1767
  | `1`, `2`, `3` | the Instances, Souls and Capabilities views |
1622
- | `Up`, `Down` | opens the workspace before or after the open one, in [the list of workspaces](#the-list-of-workspaces) as it is drawn (the chords `Alt+Up`, `Alt+Down`). Every row opens, and the list does not wrap. The terminal of the instance before or after is `Alt+Shift+Up`, `Alt+Shift+Down` ([Chords](#chords)) |
1768
+ | `Up`, `Down` | opens the workspace before or after the open one, in [the list of workspaces](#the-list-of-workspaces) as it is drawn (the chords `Alt+Up`, `Alt+Down`). Every row opens, and the moves wrap: past the last row, the first, and before the first, the last. The terminal of the instance before or after is `Alt+Shift+Up`, `Alt+Shift+Down` ([Chords](#chords)) |
1623
1769
  | `Left`, `Right` | shows the tab before or after the shown one; the tab bar does not wrap, and the focus stays where it was |
1624
1770
  | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
1625
1771
  | `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
@@ -2276,6 +2422,11 @@ with the Desktop (`packages/client/`).
2276
2422
 
2277
2423
  An add and a remove are changes: `oats tui` never ends one, and one still
2278
2424
  running as it leaves is named in one line after the screen is left.
2425
+ - **The kernel's machine sweep**, `oats session resume --json`, by the same
2426
+ kernel, from `/`, with no time limit: when the run starts, and when a
2427
+ read shows a lost session ([Resuming lost sessions](#resuming-lost-sessions)).
2428
+ It is a change, as an add is, but one still running as `oats tui` leaves
2429
+ is not named.
2279
2430
  - **The workspace of each row of that list the run has not opened** is
2280
2431
  one more read, `oats status --dir <path> --json` with `--max-age 60`, by
2281
2432
  the same kernel ([the switcher](#the-switcher)): at the start, when the
@@ -2428,6 +2579,7 @@ with the Desktop (`packages/client/`).
2428
2579
  | To | Run |
2429
2580
  |---|---|
2430
2581
  | start an agent with another harness or model | `oats session start --home <home>` with its options |
2582
+ | move an instance into or out of the background | `oats instance background <name> on\|off` |
2431
2583
  | spawn an agent on another machine | `oats spawn <soul> --server <id>` |
2432
2584
  | spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
2433
2585
  | see a capability's skills and files | `oats capabilities show <name>` |
@@ -2456,7 +2608,8 @@ version:
2456
2608
  - The Souls and Capabilities views list a workspace of this machine's
2457
2609
  souls and capabilities: both are this machine's.
2458
2610
  - There is no sorting and no mouse, and a deployment's heading cannot be
2459
- folded. An open terminal has no scrollback but the viewer's own.
2611
+ folded. An open terminal scrolls back with the viewer's own keys,
2612
+ `Shift+PageUp` and `Ctrl+B [`, and no other.
2460
2613
  - Up to four terminals are open at a time, as tabs, in at most two
2461
2614
  groups. The split cannot be resized or nested, a tab moves only between
2462
2615
  the two groups, and no tab or split is kept from one run to the next, or
@@ -2584,7 +2737,9 @@ alone. The next run removes the directory that is left, with its `tmux`,
2584
2737
  server, session, window or pane. Its probe only lists panes. An agent's
2585
2738
  own session is started, ended or restarted only by the kernel's commands
2586
2739
  of an act you confirmed
2587
- ([above](#stopping-starting-restarting-and-retiring)), and an agent's
2740
+ ([above](#stopping-starting-restarting-and-retiring)) and by the kernel's
2741
+ machine sweep, which resumes lost sessions
2742
+ ([above](#resuming-lost-sessions)), and an agent's
2588
2743
  terminal is opened by `oats session attach`, which makes its own viewer
2589
2744
  session on the agents' tmux server and removes it. The one tmux server
2590
2745
  `oats tui` runs is its own private one
@@ -2595,11 +2750,12 @@ alone. The next run removes the directory that is left, with its `tmux`,
2595
2750
  ([above](#what-it-reads-and-what-it-runs)), and a spawn's empty task file
2596
2751
  ([above](#what-it-reads-and-what-it-runs)). The processes it starts are
2597
2752
  the reads above, when you open an agent its private tmux server and the
2598
- viewers in it, one for each tab, and the acts you confirm. No read, server or viewer
2753
+ viewers in it, one for each tab, the acts you confirm and the kernel's
2754
+ machine sweep. No read, server or viewer
2599
2755
  outlives it on every way out a process can handle; after SIGKILL a read
2600
2756
  in flight runs to its own end, and the private server and its viewers end
2601
- by themselves. An act you confirmed is never ended by `oats tui`: it runs
2602
- to its own end. A spawn is ended only at its deadline, while `oats tui`
2757
+ by themselves. An act you confirmed, and the machine sweep, are never
2758
+ ended by `oats tui`: each runs to its own end. A spawn is ended only at its deadline, while `oats tui`
2603
2759
  runs ([above](#what-it-reads-and-what-it-runs)): never on the way out,
2604
2760
  and never after it.
2605
2761
  - It **changes this computer's list of deployments only through the
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.68.1** ([release notes](release-notes/v0.68.1.md)).
10
- The 0.68.1 Desktop accepts OATS CLIs `>=0.26.0 <0.69.0`.
9
+ The latest version is **OATS 0.69.2** ([release notes](release-notes/v0.69.2.md)).
10
+ The 0.69.2 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.68.1,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.2,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.68.1 first
23
- npm install -g @awebai/oats@0.68.1 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.2 first
23
+ npm install -g @awebai/oats@0.69.2 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -166,8 +166,17 @@ of the Desktop and the CLI, and an optional package pin. A change a script
166
166
  must follow is in its release's Upgrade section whether or not it is listed
167
167
  here.
168
168
 
169
- - **[0.68.0](release-notes/v0.68.0.md#upgrade):** the Desktop first, then the CLI: a 0.67 Desktop refuses a 0.68
170
- CLI. The catalog pins new package versions; after `oats sync`, a stopped
169
+ - **[0.69.2](release-notes/v0.69.2.md#upgrade):** the catalog pins
170
+ oats.framework 1.16.1 and oats.okf 5.5.0. Sync each deployment before its
171
+ instances on oats.okf 5.5.0 write proposals: an older harvester refuses
172
+ them. A soul's `background: true` waits until every deployment runs 0.69.2.
173
+ - **[0.69.1](release-notes/v0.69.1.md#upgrade):** 0.69.0 was tagged but never
174
+ published; 0.69.1 carries all of it, so follow
175
+ [0.69.0's Upgrade section](release-notes/v0.69.0.md#upgrade): the Desktop
176
+ first, then the CLI: a 0.68 Desktop refuses a 0.69 CLI. Every host that shares a workspace
177
+ runs OATS 0.68.0 or later before any of them syncs to oats.aweb 1.32.0.
178
+ - **[0.68.0](release-notes/v0.68.0.md#upgrade):** the Desktop first, then the
179
+ CLI: a 0.67 Desktop refuses a 0.68 CLI. The catalog pins new package versions; after `oats sync`, a stopped
171
180
  home can move to them with `oats instance upgrade` instead of a respawn
172
181
  ([Moving existing homes](#moving-existing-homes-to-locked-package-versions)).
173
182
  - **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.14.1 # bare version → resolves through the official catalog
58
- oats.okf: v5.3.0
57
+ oats.framework: v1.16.1 # bare version → resolves through the official catalog
58
+ oats.okf: v5.5.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
@@ -1,42 +1,28 @@
1
1
  ## Your two directories
2
2
 
3
- **`<instance-home>` is where this session starts** — the specific gitignored OATS
4
- instance directory you woke up in, given to your harness and to every lifecycle
5
- hook as `$OATS_INSTANCE_HOME`. It is not your user home (`~`), not the repository
6
- root, and not the work tree. Anything that says "your home" means this directory.
3
+ **IMPORTANT: ALWAYS FOLLOW THESE INSTRUCTIONS FOR WORKING**, here and in your
4
+ work-mode block below.
7
5
 
8
- - **Your brain and your state live here**: `AGENTS.md` (your composed
9
- instructions), `TASK.md` (this task), `instance.json` (what you were given
10
- and from where), and whatever working state your role keeps — your knowledge
11
- layer names those files, if you have one. They belong here, not in the work
12
- tree.
13
- - **Run OATS operational/lifecycle commands, and commands from active
14
- capabilities, from instance home** — `oats status`, `oats doctor`, `oats spawn`,
15
- and whatever your own capabilities add; for example, when the
16
- aweb messaging capability is active, run `aw` there too. They resolve their
17
- scope from the directory you run them in, so running them from the work tree
18
- points them at the wrong deployment. To act on a different package or config
19
- scope deliberately, pass an explicit resolved path: `oats <cmd> --dir <path>`.
20
- - **Soul work is repository work.** If your TASK is to change soul content that
21
- lives in this repository, that is ordinary code work — do it on tracked paths
22
- under `work/`, reviewed like the rest. How your own learnings reach your soul
23
- is your knowledge capability's business, and its instructions below say so if you
24
- have one.
6
+ **Your home is where this session starts** (`$OATS_INSTANCE_HOME`). It is not
7
+ your user home (`~`), not the repository root, and not the work tree.
25
8
 
26
- **`<instance-home>/work` is your repository or workspace view** — whatever your
27
- work mode grants you of the code.
9
+ - It holds your brain and state: `AGENTS.md`, `TASK.md`, `instance.json` and
10
+ your role's working state. Never put them in `./work`.
11
+ - **ALWAYS run OATS commands, and commands from active capabilities, from
12
+ instance home** (for example, when the aweb messaging capability is active,
13
+ `aw` too): they resolve their scope from where you run them. For another
14
+ scope on purpose: `oats <cmd> --dir <path>`.
15
+
16
+ **`<instance-home>/work` is your repository or workspace view**, as your work
17
+ mode grants it.
28
18
 
29
19
  - **Repository work happens there, or in the extra trees your mode block
30
20
  grants, and nowhere else**: reading, editing, building, testing, git and
31
21
  commits, on repository content. Never from the main checkout or from your
32
22
  home root, beyond what your mode block names.
33
- - **What your mode permits is the mode block's call**, immediately below. Some
34
- modes are read-only, some share a tree with others, and that block is the
35
- authority on which operations are yours to perform.
36
- - This is about where the *repository's* content lives, not a ban on writing
37
- anywhere else: the episodic files above, and whatever artifacts your role
38
- calls for (a report written to a temp file before mailing it, a scratch
39
- script), go where your task and tooling direct.
40
-
41
- Move between the two as the task needs — the boundary is what each directory is
42
- *for*, not a place to settle in.
23
+ - **What your mode permits is the mode block's call**: your mode block, below,
24
+ is the authority.
25
+ - If your TASK is to change soul content that lives in this repository, that is
26
+ ordinary repository work. How your own learnings reach your soul is your
27
+ knowledge capability's business.
28
+ - Reports and scratch files go where your task and tooling direct.
@@ -1,16 +1,11 @@
1
1
  ## Work mode: attached
2
2
 
3
- Your `./work` is a symlink to **another instance's work tree** — you share
4
- their branch and their uncommitted state. You are a guest in their workspace.
3
+ Your `./work` is **another instance's work tree**, its branch and uncommitted
4
+ state. You are a guest.
5
5
 
6
- - **Never switch branches, never rebase, never reset** — the tree belongs to
7
- its owner; your job is focused additions on top of their current state.
8
- - Keep your changes and commits **small and clearly attributable** (your
9
- instance name in commit messages where ambiguity is possible).
10
- - Do not touch files the owner is mid-editing unless your task says so; when
11
- in doubt, coordinate through your messaging capability or your spawner.
12
- - Retiring you never removes the shared tree — cleanup of the tree is the
13
- owner's concern, not yours.
14
-
15
- This mode fits service agents (harvesters, reviewers, fixers) that operate
16
- on a live instance's work in flight.
6
+ - **NEVER switch branches, rebase or reset.** Make focused additions on top of
7
+ the owner's current state; keep changes and commits small, and name yourself
8
+ in commit messages where authorship could be unclear.
9
+ - Leave files the owner is editing alone unless your task says otherwise; when
10
+ unsure, ask through your messaging capability or your spawner.
11
+ - The tree's cleanup is its owner's; retiring you never removes it.
@@ -1,40 +1,26 @@
1
1
  ## Work mode: checkout
2
2
 
3
- Your `./work` is a symlink to the repo's **shared checkout** — you are working
4
- in the same tree as the human and possibly other agents.
3
+ Your `./work` is the repository's **shared checkout**: the human and other
4
+ agents work in the same tree.
5
5
 
6
- - **Work on the currently checked-out branch; never switch branches unless
7
- explicitly asked.**
8
- - No destructive git operations (reset --hard, rebase, force-push, checkout
9
- of another branch) without an explicit human instruction.
6
+ - **Stay on the checked-out branch; never switch unless explicitly asked.**
7
+ - **NO destructive git** (reset --hard, rebase, force-push, checking out
8
+ another branch) without an explicit human instruction.
10
9
  - Work that needs its own branch goes in an extra tree, not in `work/`.
11
10
 
12
11
  ### Extra trees
13
12
 
14
- When the work needs another branch, or another repository of this deployment,
15
- create an extra tree in your home. Run this from your home; `<base>` is the
16
- remote branch the work starts from (the branch itself, when you rework an
17
- existing one):
13
+ For another branch or repository, from your home (`--preview` first; `--repo
14
+ <member key|clone path>` for another repository; `<base>`: the remote branch
15
+ to start from, or the one you rework):
18
16
 
19
17
  oats worktree add --purpose <purpose> --branch <branch> --base <base>
20
18
 
21
- It makes `.work-<purpose>` in your home, on a new `<branch>` at `origin`'s
22
- `<base>`. The repository is yours unless `--repo <member key|clone path>`
23
- names another; `--preview` shows what it would do.
24
-
25
- - It starts from the remote's current state and moves none of the clone's
26
- refs. Never start a tree from a local branch of the clone, which may be stale.
27
- - Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
28
- If it already exists in that clone, `add` refuses: use `<instance>/<branch>`.
29
- Never `-C`/`-B`, which reset a branch someone else may own.
30
- - If a capability of yours sets up new trees, `add` runs that setup, which
31
- may take minutes: give it a long timeout, or run it in the background and
32
- wait for it to exit. A killed `add` rolls back; run it again. Once it has
33
- finished, running it again with the same arguments does nothing.
34
- - The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
35
- (`<base>` when you rework an existing branch).
36
- - Before your task closes, merge each extra tree into your PR branch, or push its
37
- branch and name it in your hand-back; then
38
- `oats worktree remove --purpose <purpose>`, which keeps the branch and
39
- refuses a tree with uncommitted work.
40
- Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
19
+ - Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
20
+ (if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
21
+ - `add` may take minutes: use a long timeout; if killed, rerun it.
22
+ - Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
23
+ - Before you finish, merge each tree into your PR branch, or push it and name
24
+ it in your hand-back; then `oats worktree remove --purpose <purpose>`.
25
+ Retirement may keep a tree with uncommitted work; don't rely on it.
26
+ Details: `oats worktree --help`, and `/oats-operate` if you have it.
@@ -1,18 +1,12 @@
1
1
  ## Work mode: directory
2
2
 
3
- Your `./work` is an **instance-owned execution directory**. It is not a Git
4
- worktree, a checkout, or a link to the source instance or deployment context.
5
- The context recorded as `repo` supplies configuration; it grants no permission
6
- to edit that directory.
3
+ Your `./work` is an **instance-owned execution directory**, not a Git worktree,
4
+ checkout or link. The `repo` recorded for you supplies configuration only; it
5
+ grants no permission to edit the `repo` directory.
7
6
 
8
- - Do task work inside `./work`. No Git repository or branch is created for you;
9
- do not initialize a fake repository to satisfy a workflow. Git might discover
10
- a containing repository; that does not authorize work in the containing tree.
11
- - Access external inputs and destinations only as explicitly authorized by the
12
- task and active capabilities. This mode does not impose a storage provider or
13
- a publication protocol.
14
- - Keep canonical instructions in the instance's `AGENTS.md`; `CLAUDE.md` is its
15
- compatibility symlink. Run OATS lifecycle/capability commands from home.
16
- - Retirement removes the execution directory only after nonempty work has a
17
- verified copy in the reported recovery storage beside the home. Recovery is
18
- not publication: deliver your results through the task's own protocol first.
7
+ - Work inside `./work`. **Never initialize a fake repository**; a containing
8
+ repository Git discovers is not yours.
9
+ - Use external inputs and destinations only as your task and capabilities
10
+ explicitly authorize.
11
+ - Deliver results through your task's own protocol before you finish: the
12
+ recovery copy kept at retirement is not publication.
@@ -1,22 +1,11 @@
1
1
  ## Work mode: workspace
2
2
 
3
- Your `./work` is the **whole workspace** (the deployment/team scope), not a
4
- single repo. Every member repo under it is visible context. You are a
5
- cross-repo coordinator: your product is routing, analysis, and coordination —
6
- not code changes.
3
+ Your `./work` is the **whole workspace**, not one repository. You route,
4
+ analyse and coordinate; you do not change code.
7
5
 
8
- - **Read freely across all member repos; never edit or commit inside them.**
9
- Repo changes are routed to that repo's own agents (see `oats status` in the
10
- deployment, your tasks capability, or messaging) or to the human.
11
- - No git state operations in any member repo: no branch switching, no
12
- commits, no worktrees, no resets.
13
- - Your own working state lives in your instance home, not in any member repo,
14
- and needs no git ceremony.
15
- - If one of your capabilities delivers durable updates into a repo, its own
16
- instructions define where and how — including whether anything is committed at
17
- all, and by whom. That is its business, not an exception you take into a
18
- member repo yourself.
19
-
20
- This mode fits coordinators, dispatchers, architects, and analysts whose
21
- scope is the workspace itself; if a task needs actual edits in one repo, ask
22
- for (or route to) a worktree-mode instance of that repo's agent instead.
6
+ - **Read freely across member repositories; never edit or commit inside them,
7
+ and NEVER change their Git state** (no branch switches, resets, pulls,
8
+ stashes or worktrees). Route a repository change to that repository's agents
9
+ or to your human.
10
+ - A capability that delivers updates into a repository follows its own
11
+ instructions; that is not an exception you take yourself.