@awebai/oats 0.69.23 → 0.70.0

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 (88) hide show
  1. package/bin/oats.mjs +112 -20
  2. package/docs/capabilities.md +697 -11
  3. package/docs/capability-manifest.schema.json +66 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +330 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +210 -4
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +24 -3
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/release-notes/v0.70.0.md +155 -0
  21. package/docs/souls-and-instances.md +57 -0
  22. package/docs/trust-model.md +8 -1
  23. package/docs/tui.md +21 -1
  24. package/docs/upgrading.md +19 -5
  25. package/docs/workspaces.md +13 -5
  26. package/lib/automation-scope.mjs +1 -1
  27. package/lib/capability-show.mjs +20 -1
  28. package/lib/command-flags.mjs +2 -2
  29. package/lib/compile-cache.mjs +1 -1
  30. package/lib/core.mjs +1455 -203
  31. package/lib/errors.mjs +4 -1
  32. package/lib/home-integrity.mjs +329 -0
  33. package/lib/hook-env.mjs +107 -0
  34. package/lib/host-run.mjs +11 -3
  35. package/lib/instance-events.mjs +32 -5
  36. package/lib/instance-git.mjs +9 -0
  37. package/lib/instance-inspect.mjs +107 -9
  38. package/lib/instance-lifecycle.mjs +15 -3
  39. package/lib/instance-listing.mjs +101 -8
  40. package/lib/instance-resolution.mjs +85 -2
  41. package/lib/instance-upgrade.mjs +170 -14
  42. package/lib/kernel-features.mjs +10 -1
  43. package/lib/node-version.mjs +9 -0
  44. package/lib/provider-call-child.mjs +60 -0
  45. package/lib/provider-resume.mjs +83 -0
  46. package/lib/provider-test-seams.mjs +20 -0
  47. package/lib/read-call.mjs +2 -0
  48. package/lib/remote.mjs +33 -1
  49. package/lib/reserved-launch-env.mjs +8 -1
  50. package/lib/retire-admission.mjs +12 -1
  51. package/lib/sandbox-allowances.mjs +329 -0
  52. package/lib/schedule.mjs +14 -4
  53. package/lib/servers.mjs +38 -5
  54. package/lib/session-inspect.mjs +123 -87
  55. package/lib/session-providers.mjs +575 -0
  56. package/lib/session-receipt.mjs +93 -0
  57. package/lib/session-resume.mjs +68 -15
  58. package/lib/stable-node.mjs +3 -0
  59. package/lib/triggers.mjs +3 -1
  60. package/lib/upgrade-state.mjs +6 -1
  61. package/lib/worktree-hooks.mjs +18 -2
  62. package/lib/worktree.mjs +21 -7
  63. package/package-catalog.json +2 -2
  64. package/package.json +2 -1
  65. package/packages/client/capability-list.mjs +21 -0
  66. package/packages/client/cli-adapter.mjs +19 -4
  67. package/packages/client/cli-locator.mjs +5 -1
  68. package/packages/client/deployment-data.mjs +23 -1
  69. package/packages/client/deployment-panel.mjs +25 -3
  70. package/packages/client/home-board.mjs +33 -19
  71. package/packages/client/inspect-boundary.mjs +18 -8
  72. package/packages/client/instance-acts.mjs +30 -3
  73. package/packages/client/instance-board.mjs +206 -0
  74. package/packages/client/instance-presentation.mjs +55 -0
  75. package/packages/client/liveness.mjs +15 -4
  76. package/packages/client/own-codes.mjs +5 -1
  77. package/packages/client/remote-roster.mjs +6 -1
  78. package/packages/client/session-backends.mjs +31 -0
  79. package/packages/client/session-start.mjs +18 -6
  80. package/packages/client/spawn-apply-cli.mjs +5 -3
  81. package/packages/client/spawn-apply-contract.mjs +25 -2
  82. package/packages/client/spawn-apply.mjs +5 -1
  83. package/packages/client/spawn-messages.mjs +3 -0
  84. package/packages/client/terminal-contract.mjs +4 -0
  85. package/packages/client/waiting-on-you.mjs +12 -2
  86. package/packages/tui/lib/model.mjs +14 -3
  87. package/packages/tui/lib/store.mjs +12 -3
  88. package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/desktop.md CHANGED
@@ -270,7 +270,7 @@ workspace on a server: `name — server`).
270
270
 
271
271
  The sidebar, top to bottom: the **Workspace** heading, with **Add local
272
272
  workspace…** (the **+**) at its end, over the list of workspaces; a thin line;
273
- two pinned rows, **Home** and **Automations**, drawn like the
273
+ three pinned rows, **Home**, **Workspace** and **Automations**, drawn like the
274
274
  instance rows (Automations shows a red dot, and says "a run failed", while a
275
275
  schedule's last run failed: see [Scheduling agents](#scheduling-agents-and-wake-messages));
276
276
  another line; **Agents**, a heading with the running count over the list of
@@ -288,42 +288,63 @@ for the keys. A window opens on **Home**: at launch, and after you choose a work
288
288
  for it. Connections is in the
289
289
  command palette (**Connections**, among its sections), and the palette opens with its
290
290
  shortcut or the leader (Ctrl+Space) then `k`.
291
- **Home** answers two questions on one page: what needs you, and what you
292
- have.
293
-
294
- - **The board.** **Needs you** lists the agents waiting on you, each with its
295
- message, newest first; **Running** lists the live ones, newest first. A
296
- group with nobody in it isn't shown. Stopped agents aren't on the board, and
297
- a live agent is "running": OATS doesn't report working or idle yet, and the
298
- Desktop doesn't guess it. There is no "New" group yet either, since nothing
299
- records which agents stopped or finished since you last looked. Enter (or a
300
- click) on a row opens it as it does in the roster: a running agent's
301
- terminal, a stopped one's Start.
302
- - **The overview.** Agents, Souls, Capabilities, Teams, Machines and Graph,
303
- each with what you have ("You have 4 souls"). Enter opens that part of the
304
- Workspace page on its tab (the Machines canvas stands in for the Graph for
305
- now), and Esc there comes back to Home. Agents opens **Home › Agents**: every
306
- agent, running or stopped, with its soul and machine, its state, and who
307
- started it (the person it's attributed to, or the agent that spawned it).
308
- An agent waiting on you wears the needs-input mark there too, and says
309
- "needs you". Esc or the **‹ Home** button returns.
291
+ **Home** answers two questions on one screen: what needs you, and what you
292
+ have. It is one centred column. Top to bottom:
293
+
294
+ - **Needs you.** The agents waiting on you, newest first: each with the
295
+ needs-input mark, its name, its soul and machine, and its message. Enter (or
296
+ a click) opens one as it does in the roster. Eight show at most, then **Show
297
+ all N**, which shows the rest in place. With none, one quiet line says
298
+ "Nothing needs you."
299
+ - **One summary line**, such as "24 agents · 21 running · 3 need you · 0
300
+ stopped" (and how many have no known state, when some don't). A live agent
301
+ is "running": OATS doesn't report working or idle yet, and the Desktop
302
+ doesn't guess it.
303
+ - **The workspace, as one row of tiles**, each a button with its count:
304
+ **Agents**, **Souls**, **Capabilities**, **Teams**, **Machines** and
305
+ **Automations** (with the sidebar row's red dot while a run failed). A count
306
+ still being read says "Counting…", and one that couldn't be read says so;
307
+ nothing is guessed. Enter opens that part of the Workspace page on its tab
308
+ (Machines on its List), and Esc there comes back to Home; Automations opens
309
+ its page. Agents opens **Home › Agents**: every agent, running or stopped, in
310
+ the sidebar's order (pinned ones first), with its soul and machine, its
311
+ state, and who started it (the person it's attributed to, or the agent that
312
+ spawned it). An agent waiting on you wears the needs-input mark there too,
313
+ and says "needs you". Esc or the **‹ Home** button returns.
314
+ - **Running**, under the tiles: the first five running agents, in the
315
+ sidebar's order, then **Show all N running**, which shows the rest in place
316
+ (and **Show fewer** folds them back). The heading says they run; no row
317
+ repeats it.
310
318
  - **A workspace with no agents yet** shows what OATS does in two lines and
311
- three keys (New agent, the command palette, Home), then the overview.
312
-
313
- Home has no key of its own yet: the palette's **Home** (among its sections)
314
- opens it. The
315
- board never changes the roster's order: urgency is sorted on Home only.
319
+ three keys (New agent, the command palette, Home), then the tiles.
320
+
321
+ Home has no key of its own yet: its row, or the palette's **Home** (among its
322
+ sections), opens it, and always on its board, also from **Home › Agents**. Home never changes the roster's order: urgency is sorted
323
+ on Home only.
324
+
325
+ **The Workspace page** has its own row, under Home's, and ⌘2 / Ctrl+2. Its
326
+ head says where you are and how to get back, **Home › Workspace › Souls**,
327
+ above its tabs (Souls, Capabilities, Teams, Machines, Setup): Home and
328
+ Workspace are links (Workspace opens the page on Souls). A soul's, a
329
+ capability's or a team's page carries the same trail in its bar, one level
330
+ deeper (**Home › Workspace › Souls › dev**, and a skill one more), each part
331
+ above the page a link. Esc goes up one level: from a soul's page to Souls,
332
+ then to Home. Every way onto the page (its row, a Home tile, the palette, the
333
+ key, a soul's or a capability's page) marks the Workspace row, never Home's.
316
334
 
317
335
  **The command palette** (⌘K / Alt+K) is the one place to reach everything.
318
336
  It lists, in order: the agents that need you (the newest first), your recent
319
337
  agents (the sidebar's tree, the one you used last on top), the sections
320
- (Home, Workspace overview and its tabs, Automations, Connections), the commands,
338
+ (Home, Workspace and its tabs, Automations, Connections), the commands,
321
339
  and one **New agent: <soul>** row per soul. Type to narrow it; `>` keeps only
322
340
  the commands and `+` only the souls.
323
341
 
324
342
  **The status line** runs along the bottom of the window. It shows the three
325
343
  keys most useful where you are (in the roster: Enter, Stop and the palette;
326
- in a terminal: the leader, close tab and the palette), says in one line why a
344
+ in a terminal: the leader, close tab and the palette); on the Workspace pages,
345
+ their own keys: **↑↓ move · Enter open · v table · Esc Home** on Souls (**v
346
+ grid** in the table), the same without **v** on Capabilities, and **↑↓ move ·
347
+ Enter open · Esc back** on a soul's, a capability's or a team's page. It says in one line why a
327
348
  key could not act (the leader's line is drawn there), says what was just done
328
349
  ("Workspace onboarded. The lock is written."), says when the terminal in front
329
350
  loses its server and when it is back (the pane keeps its countdown and its
@@ -355,7 +376,8 @@ hear the new size once, when you let go.
355
376
 
356
377
  **Appearance.** The palette's **Appearance…** and ⇧⌘Space / Ctrl+Shift+Space
357
378
  open the Appearance sheet, with three parts. **Theme**: System (Omarchy's theme on a computer that runs Omarchy, else
358
- the system's light or dark setting; it was "This computer"), Dark, Light, and
379
+ the system's light or dark setting; it was "This computer"), Dark (Tokyo Night's
380
+ blues and greys in the window; the terminals keep their own colours), Light, and
359
381
  More themes… (Solarized). **Font**, the terminals' font (the window's own
360
382
  text is always the system's interface font):
361
383
 
@@ -428,8 +450,8 @@ a choice saved for it is ignored.)
428
450
  - **The current workspace** has its circle filled, like a running
429
451
  instance's, and its name in bold; the others have the ring a stopped
430
452
  instance has. It has no background of its own: the selection's background
431
- marks the current page (Home, whose row also stands for the Workspace page it
432
- opens, or Automations), so the
453
+ marks the current page (Home, Workspace, whichever of its tabs or pages
454
+ shows, or Automations), so the
433
455
  sidebar fills one "you are here" row. A screen reader hears it as current,
434
456
  and the list's description names it, by the same name as its row.
435
457
  - **The needs-input mark.** A row has an exclamation mark (a small amber
@@ -507,18 +529,24 @@ other window.
507
529
  ## Capabilities and spawning
508
530
 
509
531
  **Workspace › Capabilities** lists every capability of the workspace as one
510
- list of rows. Core capabilities (knowledge, messaging and tasks) come first,
532
+ list of rows. Its first line says what a capability is, how many the workspace
533
+ has and how many are official, and what the ✓, **core** and **default** say
534
+ (**default** only where the workspace reports its defaults). Core capabilities
535
+ (knowledge, messaging and tasks) come first,
511
536
  in that order, each with a dim **core** tag; every other capability follows by
512
- name. There are no sections, repository groups or colour marks. Each row
537
+ name. There are no sections, repository groups or colour marks. The rows sit
538
+ on the page, a thin rule under each, with no box around them; a row lightens
539
+ under the pointer and takes the selection tint when focused. Each row
513
540
  shows:
514
541
 
515
542
  - the capability's name;
516
- - who made it: a small ✓ in a circle for an official one (its tooltip says
543
+ - who made it, right after the name: a small ✓ in a circle for an official one (its tooltip says
517
544
  which fact made it official: **Official: in the OATS catalog** or **Official:
518
545
  from the OATS repository**), or **by** its source (a member repository's
519
546
  name, or a git package's repository);
520
547
  - one line of what it does (the manifest's description, cut to one line);
521
- - its tags: **core**, **default** for one the workspace gives every soul,
548
+ - its tags, as small pills (**core** in a thin frame, **default** on a quiet
549
+ fill): **core**, **default** for one the workspace gives every soul,
522
550
  **default · off** for one the workspace turns off, and **repo only** for one
523
551
  only its own repository's souls can use.
524
552
 
@@ -535,12 +563,18 @@ A kernel fact for "official" is
535
563
  name and version are not on this list: **Setup**'s Packages box shows them,
536
564
  and so does the capability's page.
537
565
 
538
- One sentence above the list says what defaults are: the capabilities the
539
- workspace gives every soul, so its agents share one way of working. A soul
540
- can turn a default off and choose its own instead. The sentence also says
541
- which core slot no default fills, and names a declared default the list can't
542
- show as a row. A workspace that sets no defaults (a standalone deployment, for
543
- example) says so in that sentence. The search never narrows it. It is read
566
+ Above the list, **Workspace defaults** shows what the workspace gives every
567
+ soul, so its agents share one way of working. Its title and **All
568
+ capabilities**' are in small capitals, as the Souls groups' are. One sentence says what defaults
569
+ are (a soul can turn a default off and choose its own instead); then **Core**,
570
+ one line each for Knowledge, Messaging and Tasks with the capability that fills
571
+ it (its name alone when the list doesn't hold it, or "No default"), and **Additional**, every other default, a turned-off one
572
+ tagged so. Each default is the list's own row, with its one line and where it
573
+ comes from, and opens its page; ↑ and ↓ move across them. The list follows,
574
+ under **All capabilities**. The sentence also names a declared default the
575
+ list can't show as a row. A workspace that sets no defaults (a standalone
576
+ deployment, for example) says so. The search narrows only the list, never the
577
+ defaults. It is read
544
578
  from `oats workspace status --json`: an OATS that doesn't report the defaults
545
579
  shows no sentence and no tag, and the Desktop doesn't guess them from the
546
580
  souls. The defaults are declared in the workspace file; the page only shows
@@ -577,7 +611,12 @@ one off and name its own in its place.
577
611
  tab or the workspace closes it too.
578
612
 
579
613
  **Workspace › Souls** lists the souls the workspace offers. Its first line says
580
- what a soul is. The souls are grouped by where they come from: the workspace's
614
+ what a soul is, how many the workspace has and how many have agents running,
615
+ and how the page is ordered ("You have 10 souls, 4 with agents running, grouped
616
+ by where they come from; maintainers first, then experts, developers,
617
+ operations. Enter opens one.").
618
+ Each group's heading is its name in small capitals and its count
619
+ ("AGENTS · member repo · host · 6 souls"). The souls are grouped by where they come from: the workspace's
581
620
  own repository first, then its other member repositories, then each package,
582
621
  then the external souls. Inside a group they are in kind order: maintainers,
583
622
  experts, developers, operations, then the rest, each by name. The kind is read
@@ -588,10 +627,12 @@ reports no role for a soul yet, so the name is the rule until it does
588
627
  ([#1980](https://github.com/oats-project/oats/issues/1980)).
589
628
 
590
629
  The souls show as a grid of cards or as a table: **v** (or **Grid** | **Table**
591
- in the toolbar) switches between them, and each window remembers its choice,
592
- also after a restart. A card shows the soul's name, what it does, how many of
593
- its agents run, and its kind; a soul a spawn here would refuse also says why,
594
- above its count. The table has the same souls as rows: name, what it does, kind,
630
+ beside the page's title) switches between them, and each window remembers its choice,
631
+ also after a restart. The grid has three columns at most, fewer in a narrow
632
+ window. A card shows the soul's name, larger and bold, what it
633
+ does, in muted text on two lines at most, and a smaller line with how many of its agents run
634
+ and its kind; a soul a spawn here would refuse also says why, in one quiet
635
+ line above its count, the whole sentence on its page. The table has the same souls as rows: name, what it does, kind,
595
636
  agents running, harness · model, and **Ready** (or why a spawn here would be
596
637
  refused; **—** when this OATS does not report it). A card or a row's name
597
638
  opens the soul's page. A new agent of a soul starts from **New agent** on its
@@ -599,8 +640,10 @@ page, from Quick Open, or from the palette. Souls of a member repository that
599
640
  has not confirmed its membership are listed last, under **Not available**,
600
641
  with the reason; they open nothing.
601
642
 
602
- A soul's page (open a soul from **Workspace › Souls**) is one column. Under its
603
- name and what it does, a block of facts: **Harness · model** (what a spawn here
643
+ A soul's page (open a soul from **Workspace › Souls**) is one column, in the
644
+ same type and spacing as the lists: its name as the page's one large line, the
645
+ section titles in small capitals, the capability rows as Capabilities' rows.
646
+ Under its name and what it does, a block of facts: **Harness · model** (what a spawn here
604
647
  runs, and where that choice came from), **Teams** (the teams its agents may
605
648
  join, the default marked; with team model v2, **Teams on this computer** folds
606
649
  out the editable list), **Knowledge** (the nodes it owns and reads, when it
@@ -1072,6 +1115,96 @@ the operation says so, with what to do: stop it and upgrade it (`oats instance
1072
1115
  upgrade`), or start a new agent of its soul. The details are in
1073
1116
  [packages/desktop/docs/desktop-mail-sheet.md](../packages/desktop/docs/desktop-mail-sheet.md).
1074
1117
 
1118
+ ## The agent view: facts and questions
1119
+
1120
+ With an OATS that reports the agent's board (feature `instance-board`; the
1121
+ agent writes it with `oats instance board set` and `oats instance board ask`,
1122
+ [docs/desktop-cli-api.md](desktop-cli-api.md)), an agent's terminal tab is its
1123
+ **agent view**. Top to bottom:
1124
+
1125
+ 1. **Facts**: what the agent keeps in your view, one compact row each,
1126
+ `label · value unit`, with "updated 4 min ago". At most three show; **N
1127
+ more** unfolds the rest. While the view is open the Desktop reads each
1128
+ fact's history once, and a number that changed draws a small sparkline.
1129
+ A link shows as the agent's, with its host (`dev-a says: github.com…`). A
1130
+ press shows its whole address over the top of the terminal, wrapped, the
1131
+ host in bold, with **Open in browser** beside it: only that press opens it,
1132
+ in your browser. Esc closes it. An address that looks like it carries a
1133
+ secret (a token in it) is never shown: the fact shows without its link. **×**, or
1134
+ **u** on a focused fact, hides it on this computer only: the agent's board
1135
+ is unchanged, and the fact shows again when its value changes. **N hidden ·
1136
+ show** brings them all back.
1137
+ 2. **The agent's own terminal**, unchanged: the same viewer, the same cell
1138
+ geometry, the only part that scrolls (a long context scrolls inside its
1139
+ own open fold, at most twelve lines tall). The board leaves it at least
1140
+ 120 px, or 40% of the pane: in a short pane the facts give way to one (the
1141
+ rest stay behind **N more**), then the questions drop their key hint, then
1142
+ an open context shortens to three lines. A pane too short even for that
1143
+ keeps its terminal smaller, and a number types only while at least two of
1144
+ its lines show. It gives up exactly the rows the
1145
+ facts and the questions take.
1146
+ 3. **Questions**: one at a time, under the terminal, so they sit right by the
1147
+ agent's input line at the bottom of its screen. "question 2 of 3", ‹ › and
1148
+ the dots turn them, and so do Tab / Shift+Tab and ← / → while the questions
1149
+ have the focus. A question with context has a **Context** fold, attributed
1150
+ to the agent, as plain text: **c** opens or closes it and moves the focus
1151
+ there, where Tab moves into its text. With no open question there is no zone.
1152
+
1153
+ **What the view says when it can't show something.** History and context come
1154
+ from a second read while the view is open (`oats inspect --home <h> --board`,
1155
+ sent only when this computer's OATS, and for an agent on another machine that
1156
+ machine's OATS too, has the feature). The view reads it when it opens, when a
1157
+ fact changes and when a question with context is asked, never on the roster's
1158
+ poll. When that read fails, comes back in a shape the Desktop can't read, or
1159
+ comes from an OATS without the feature, the facts strip and the context fold
1160
+ say which. A board the Desktop can't read, or one with entries it had to leave
1161
+ out, says so too. None of these hides a question or reads as "no questions".
1162
+
1163
+ **Answering.** The questions and the facts are focus regions: from the
1164
+ terminal, **Ctrl+Shift+F6** moves to the questions, and F6 / Shift+F6 move on
1165
+ from there (the facts come before the terminal, the questions after it). The
1166
+ palette's **Agent: questions and facts (focus)** moves through the questions,
1167
+ the facts and back to the terminal. Esc goes back to the terminal. A number, or a press on an
1168
+ option, puts `<id>: <option>` on the agent's input line, for example
1169
+ `q2: Yes, one clean commit`, and gives the terminal the focus. Nothing is sent:
1170
+ your Enter in the terminal sends it, as if you had typed it, so you see what
1171
+ goes. No bare digit is ever typed, and nothing is typed into a terminal that
1172
+ isn't on screen: a press whose terminal left the screen while the Desktop read
1173
+ the agent's claims types nothing. After a press the card says, quietly, "Typed
1174
+ on the input line: press Enter in the terminal to send it." until your next
1175
+ input in the terminal or a change on the board. The Desktop doesn't guess what
1176
+ the input line holds: the card stays until the agent clears the question once
1177
+ it has read your answer, and a second press types again, as typing would.
1178
+
1179
+ While the terminal is in its scrollback (you scrolled up with the
1180
+ wheel or Shift+PgUp), nothing is typed either, because the scrollback would
1181
+ read the answer's first letter as its own key: the zone says "The terminal is
1182
+ in its scrollback: press q or scroll to the bottom, then press the number
1183
+ again." The Desktop checks the terminal just before it types, and types only
1184
+ when the check says it isn't in its scrollback: when it can't tell (the check
1185
+ failed), nothing is typed and the zone says "The answer wasn't typed: the Desktop
1186
+ couldn't check the terminal's scrollback. Type it there yourself, or press the
1187
+ number again." On an agent on another machine the numbers are disabled from the
1188
+ start, since its terminal can't be checked from this computer, and the zone says
1189
+ "This agent runs on another machine: type the answer in its terminal (for
1190
+ example q1: Yes)." (follow-up: #2029). The check and the typing are two steps a few milliseconds apart:
1191
+ if you enter the scrollback in exactly that moment, tmux can still read the
1192
+ answer's first letter as a scrollback key. That window is not closed.
1193
+
1194
+ **While a dialog is open** (the agent has a live `permission` or `question`
1195
+ claim, from its harness or any other producer), the numbers are disabled and
1196
+ the zone says "The agent's terminal is showing a prompt: answer it there
1197
+ first." The Desktop reads the agent's claims for this when the view opens and
1198
+ when they change, because the roster row shows only the newest one.
1199
+
1200
+ The board's own question is the agent's needs-input claim (reason
1201
+ `attention`), so the sidebar mark, the tab's mark and Home's "needs you" read
1202
+ it as before. In the agent view it shows in the question zone, not in the
1203
+ waiting row. Any other claim keeps the waiting row described above. Without
1204
+ the feature (an older OATS), the tab is the terminal and its waiting row, as
1205
+ before. A tab on another machine shows the board when that machine's OATS has
1206
+ the feature.
1207
+
1075
1208
  ## Copy from a terminal
1076
1209
 
1077
1210
  Drag over an agent's output to select it, as in any terminal. The selection
@@ -1493,7 +1626,7 @@ then requires that launch to reactivate the retained tab with exactly
1493
1626
  one viewer and no terminal focus event. CDP sends a key to the window;
1494
1627
  independent tmux pane/output reads prove no input reached the inert harness. The stopped fixture stays selected
1495
1628
  only, with no tab or Start dialog, on Home (its row current and its view
1496
- shown, since Home's row also stands for the Workspace page). The smoke also
1629
+ shown). The smoke also
1497
1630
  asserts that viewer cleanup restores its private tmux baseline. The fixture's
1498
1631
  workspace/member source, soul definition and inert harness executable are authored by the test-only
1499
1632
  [`launch-fixture.mjs`](../packages/desktop/test/helpers/launch-fixture.mjs).
@@ -37,8 +37,12 @@ variables point at are described in
37
37
 
38
38
  ## Backends
39
39
 
40
- tmux is the only session backend. `oats spawn --backend tmux` is accepted (it
41
- is the default); `tmux` must be installed on the execution host. A launched
40
+ tmux is the kernel's own session backend, and the default: `oats spawn
41
+ --backend tmux` is accepted, and `tmux` must be installed on the execution
42
+ host. A capability can supply another backend, a
43
+ [session provider](#session-providers), which `--backend <name>` selects.
44
+ `sessionBackends` in `oats version --json` lists the kernel's own (`["tmux"]`),
45
+ never a provider. The rest of this section is tmux. A launched
42
46
  home keeps the session it recorded: `session start` and `restart` never
43
47
  re-read the defaults. The session target is recorded twice: in
44
48
  `instance.json` and in an independent lifecycle receipt. Every session command
@@ -687,7 +691,8 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
687
691
  `OATS_OPERATION`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`, `OATS_KIND`,
688
692
  `OATS_TASK`, `OATS_HARNESS`, `OATS_HARNESS_EXECUTABLE`,
689
693
  `OATS_PREVIOUS_HARNESS`, `OATS_RUNTIME`,
690
- `OATS_PREVIOUS_RUNTIME`, `OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
694
+ `OATS_PREVIOUS_RUNTIME`, `OATS_BACKEND`, `OATS_PREVIOUS_BACKEND`,
695
+ `OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
691
696
  `OATS_TRIGGER_EVENT_FILE`, `OATS_TEST_LOGIN_SHELL` (a test seam that replaces
692
697
  the login shell, honoured only for a process whose `HOME` is not your home
693
698
  directory; a launch configuration cannot set it),
@@ -923,6 +928,207 @@ other instance whose window is in that session, not only the one you are
923
928
  moving. And a window that a viewer still links would live on in that viewer,
924
929
  so the next start would create a second window for the same home.
925
930
 
931
+ ### Session providers
932
+
933
+ A kernel that lists the feature `session-providers` (`oats version --json`)
934
+ can run an instance on a session backend that a capability supplies: the
935
+ agent runs where the provider runs it, and OATS keeps the instance's home,
936
+ its records, its lifecycle and its answers. What a capability declares and
937
+ answers is in
938
+ [capabilities.md](capabilities.md#session-providers-sessionproviders). tmux
939
+ homes are unchanged.
940
+
941
+ **Selecting one.** `oats spawn <soul> --backend <name>`, a schedule's
942
+ `backend` and a trigger's `spawn.backend` take a provider's name. The
943
+ provider is one that a capability of that instance declares:
944
+ `oats inspect --soul <soul> --json` lists them under `sessionProviders`
945
+ (`[{name, capability}]`), and so does `oats inspect --home`. Refused before
946
+ anything is created, and shown by a spawn preview:
947
+
948
+ | Code | When |
949
+ |---|---|
950
+ | `E_BACKEND_UNKNOWN` | no capability of the instance declares the name, or declares it malformed; the message names the backends available |
951
+ | `E_BACKEND_AMBIGUOUS` | two capabilities of the instance declare the name (a spawn, and a start or restart of a home whose modules now do) |
952
+ | `E_BACKEND_HARNESS` | the provider does not run the launch's harness |
953
+ | `E_BACKEND_LAUNCH_ARG` | the launch configuration declares an `executable`: a provider runs the harness itself |
954
+ | `E_BACKEND_WIRE` | the provider speaks another version of the session-provider wire than this kernel (its manifest's `wire`), or declares none: use the release of its capability that goes with this OATS |
955
+ | `E_BACKEND_NOT_READY` | the provider's own readiness check, asked right before the launch, says it cannot take it |
956
+ | `E_BACKEND_SANDBOX_HOST` | a capability asks to add a host to the session's sandbox that it may not ask for: it declares `sandboxDomains` and fills none of the instance's messaging, knowledge or tasks slots, its line is malformed, its setting's value gives no plain host, its file is not the deployment's own, its setting was given to this one spawn (`--provider <capability> <setting>=…`: a launch's own argument is never a host source), or the directory the sandbox may write (the deployment's events directory) is reached through a symbolic link or is no directory ([Sandbox allowances](capabilities.md#sandbox-allowances-sandboxdomains-the-launch-inputs-sandbox)) |
957
+
958
+ A provider can also refuse the launch with its own `E_BACKEND_*` code (a
959
+ launch environment entry or an argument it cannot carry), which OATS relays;
960
+ the spawn is then rolled back.
961
+
962
+ **What OATS checks for a provider launch, and what it does not.** The launch
963
+ configuration, the harness, the model, yolo, the capabilities' hooks and the
964
+ launch environment are decided as for tmux and handed to the provider. The
965
+ checks about a terminal pane are skipped, because no pane runs the harness:
966
+ the harness executable on the pane's `PATH`, folder trust, the Claude login
967
+ credential, the development-channel prompt, the native-record wrapper. The
968
+ provider's readiness covers what they covered. One check stays: a
969
+ capability's harness-package requirement (`requires`) is probed for a
970
+ provider launch too, on this host, unless the row says which backends it is
971
+ for (`backends: ["tmux"]` leaves it out of a provider launch;
972
+ `["session-provider"]` makes it one of provider launches only).
973
+
974
+ **Records.** A provider home's `instance.json` carries `backend: "<name>"`
975
+ and `session: {provider, endpoint}` (`provider`: the capability; `endpoint`:
976
+ the provider's own locator, at most 4 KiB, `null` before the first launch),
977
+ and no `tmux` and no `command`; its launch recipe's `executable` is `null`.
978
+ Its receipt records `runtime: {launched, backend, provider, endpoint,
979
+ stoppedAt}`. The two must agree as for tmux: `E_RUNTIME_AUTHORITY_MISMATCH`
980
+ otherwise, whose `details.fields` are `backend`, `session.provider` and
981
+ `session.endpoint`.
982
+
983
+ The receipt of a provider home also records its **composition**:
984
+ `composition: { version: 1, store: "<name>", modules: { "<capability>": {
985
+ from, commit } }, capabilityRuntime: [ <row> ], previous?: { store, modules,
986
+ capabilityRuntime } }`: which store holds the
987
+ kernel's own copies of the home's modules
988
+ (`<instances>/.oats-retirement/modules/<hash of the home>/<store>/`), which
989
+ modules the home has and where each came from, and the capability rows the
990
+ spawn resolved; `previous`, after an upgrade, is the pair that upgrade
991
+ replaced, which an undo names again. For such a home the kernel runs its own copy of a module,
992
+ never the home's, and reads a capability's settings and hook commands from
993
+ this record alone
994
+ ([What the kernel trusts in a provider home](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
995
+ A tmux home's receipt has no such key, and the kernel keeps no copy of its
996
+ modules. A kernel from before it ignores the key: one from before session
997
+ providers still refuses every session verb on a provider home, and one that
998
+ knows providers and not this record runs the home's own copies, as it
999
+ always did. A provider home whose receipt has no `composition` (a kernel
1000
+ from before it spawned the home) runs nothing on this kernel: retire it and
1001
+ spawn it again.
1002
+
1003
+ **The lifecycle of a provider home is one state machine**, set out in
1004
+ [its design record](design/2026-11-20-provider-home-lifecycle.md): the
1005
+ states its records spell, what each verb does in each, in what order it
1006
+ writes, and what happens when two things cross. In short:
1007
+
1008
+ - The receipt's `runtime` carries `launchSent` (an instant) **while a launch
1009
+ that was sent to the provider has no recorded outcome**: written right
1010
+ before the provider's launch is called, by a spawn and by a start, kept
1011
+ until the launch's endpoint is in the receipt *and* in the record, and
1012
+ removed last. A launch that is killed leaves it there.
1013
+ - Such a home is **unsettled**: a session may run that no record names. It
1014
+ reads as unknown (`oats session inspect` answers `E_SESSION_UNAVAILABLE`,
1015
+ its status row `running: null`, `runtimeState: "unreachable"`), during a
1016
+ launch as after one that died; its record is not compared with its receipt
1017
+ meanwhile; input to it is refused, nothing sent.
1018
+ - A stop, a start, a restart and a retire **settle** it first: the provider
1019
+ is asked to stop whatever session rooted at the home was created since
1020
+ that instant (`stop` with `endpoint: null` and `launchSent`). Confirmed, a
1021
+ home that was never launched is as it was, and one launched before is
1022
+ stopped; not confirmed is `E_SESSION_STOP_FAILED`, and the next verb asks
1023
+ again.
1024
+ - For a home that was **never launched**, the receipt reads `runtime:
1025
+ {launched: true, backend, provider, launchSent}` meanwhile and
1026
+ `instance.json` `launched: true`, both without an endpoint. A kernel from
1027
+ before session providers reads that as a launch it cannot address and
1028
+ refuses every verb on the home, a retire included, where it would have
1029
+ retired a home it read as never launched.
1030
+
1031
+ **The verbs.**
1032
+
1033
+ | Verb | On a provider home |
1034
+ |---|---|
1035
+ | `session inspect` | the provider's `present`, `state` and `running`, with `backend`, `session` and `open` (`{label, url}` or `null`: what to show instead of a terminal); no `paneId`, no `size`. A provider that fails, is slow or answers outside the contract is `E_SESSION_UNAVAILABLE`, never "stopped" |
1036
+ | `session input` | the provider sends the text. `submitted: true` only when it was dispatched; `E_SESSION_PROMPT_OPEN` (a prompt is open in the session: nothing was sent) and `E_SESSION_INPUT_QUEUED` (the provider queued it and withdrew it) are the provider's refusals; anything else is `E_SESSION_INPUT_FAILED`. An input to a lost session is a resume ([below](#provider-homes-lost-sessions)) |
1037
+ | `instance stop` | records the stop, then asks the provider to stop the session (`E_SESSION_STOP_FAILED` when it does not confirm; the home stays recorded as stopped). A stop of a home that is already stopped asks the provider once more: run it again to finish a stop the provider did not confirm |
1038
+ | `session start` | launches a new session, a fresh conversation on `TASK.md`, and records its endpoint. Refused when a session is there that OATS did not stop: `E_SESSION_RUNNING` when it reads `running: true`, else `E_SESSION_UNKNOWN`. For a home OATS stopped it first asks the provider to stop once more, and refuses `E_SESSION_STOP_FAILED` when that is not confirmed |
1039
+ | `session restart` | stop, then start, under one lifecycle claim |
1040
+ | `session start --resume` | sends the resume notice through the provider's input; nothing is launched ([below](#provider-homes-lost-sessions)) |
1041
+ | `session attach` | `E_SESSION_NO_TERMINAL`; the message carries inspect's `open` link when there is one |
1042
+ | `oats retire` | records the stop, asks the provider to stop, checks that no process works in the home, then runs the retire hooks and removes the home ([souls-and-instances.md](souls-and-instances.md#retiring-a-home-on-a-session-provider)) |
1043
+
1044
+ **Stop stays stopped.** OATS records `stoppedAt` in the receipt at every stop
1045
+ it makes (`oats instance stop`, a restart's stop, a retire, the host's
1046
+ shutdown), before it calls the provider, and a start clears it. While it is
1047
+ set, inspect answers stopped (`present: false`, `running: false`) without
1048
+ calling the provider, and every input is refused `E_SESSION_NOT_RUNNING`
1049
+ before any call: `oats session input`, a scheduled wake (which never starts
1050
+ a provider home), a client's input, the messaging broker's delivery. A stop
1051
+ that lands while an input is being sent still wins: OATS asks the provider
1052
+ to stop the session again and answers the input `E_SESSION_NOT_RUNNING`, so
1053
+ a mail stays unread and comes again. A
1054
+ session stopped in the provider's own interface sets nothing in OATS, and
1055
+ the provider may restart it on the next input: **stop an OATS agent with
1056
+ OATS**.
1057
+
1058
+ **Status.** A provider home's row of `oats status --json` carries `backend`,
1059
+ `session: {provider}`, `tmux: null`, `open`, `running` (`true`, `false`, or
1060
+ `null` where the provider cannot tell) and `runtimeState`, always set:
1061
+ `unknown`, `shell`, `stopped` or `unreachable` (with `runtimeError`). On the
1062
+ host where the home lives the row's `session` also carries `threadId`, when
1063
+ the provider's endpoint names one, so a tool on that host can match a session
1064
+ to its instance. The endpoint itself is on `oats session inspect --home` and
1065
+ on a spawn's and a start's answer, on that host only: **nothing of it is
1066
+ relayed** by `oats server roster` or `--server`, whose rows and answers carry
1067
+ `session: {provider}`. A tmux row carries `backend: "tmux"`; a row with no
1068
+ `backend` (an older kernel, an older routed host) is a tmux row. Status asks
1069
+ each provider once per group of homes where it can (`inspectMany`), falls
1070
+ back to one `inspect` per home when a batch is bad (never after one that
1071
+ timed out), gives all its providers 30 s together, and asks nothing about a
1072
+ home OATS stopped, which keeps its last endpoint until its next start.
1073
+ `waitingOnYou` is the producers' claim, as for tmux, read while the session
1074
+ is there and not in error.
1075
+
1076
+ <a id="provider-homes-lost-sessions"></a>
1077
+
1078
+ **Lost sessions, and the resume.** An OATS stop is the intent that keeps a
1079
+ home down; only a lost session is resumed, in its own conversation, on the
1080
+ host where the home lives. Two provider homes read `sessionEnd: "lost"`:
1081
+
1082
+ - one stopped by **`oats host run`'s shutdown**. That stop records
1083
+ `stoppedAt` like any other, so input stays refused while the host or the
1084
+ container goes down, and the home's stop receipt says the host's shutdown
1085
+ wrote it. An operator's stop after it withdraws that. The shutdown stops
1086
+ every provider home OATS has not stopped, whatever its session reads, and
1087
+ asks no provider to find them (`oats session resume --plan
1088
+ --without-provider-inspect`), so a provider that goes down with the host
1089
+ cannot hold it up.
1090
+ - one whose session is **gone while OATS did not stop it**: the provider
1091
+ answers `present: false`. A provider reads a session in error this way.
1092
+
1093
+ The sweep (`oats session resume`: the Desktop and the TUI when they open,
1094
+ `oats host run` at its start and each minute) resumes both with `oats session
1095
+ start --resume --home <home>`, which you can also run for one home: it clears
1096
+ the stop, if there is one, and sends one resume notice through the
1097
+ provider's input. Nothing is launched, and a home an operator stopped stays
1098
+ stopped. The rules of that resume:
1099
+
1100
+ - **The cap.** A lost session's resume is counted against the home, at most
1101
+ 3 in an hour within one boot, as the sweep bounds a tmux home's starts. The
1102
+ kernel counts before it calls the provider, and **any input to a lost
1103
+ session is a resume** (a mail the broker delivers, a scheduled wake): the
1104
+ provider would restart the session on it. At the cap the resume and the
1105
+ input are refused `E_SESSION_NOT_RUNNING`, nothing is sent, a mail stays
1106
+ unread, and the sweep's row is `refused`, `keeps-getting-lost`. A stop with
1107
+ the host is no crash and is not counted. A resume the provider itself
1108
+ refuses is not counted either (nothing was sent); one whose call fails is,
1109
+ since the provider may have restarted the session.
1110
+ - **The last run's processes.** A resume of a lost session waits until no
1111
+ process works in the home (a harness can outlive its server's crash), for
1112
+ at most 150 s. Past that it refuses `E_SESSION_UNKNOWN`, names the
1113
+ processes and never kills them; it is not counted, and the next sweep tries
1114
+ again. An input does not wait: it is refused at once.
1115
+ - **The notice is input.** It is not sent while a claim is open that holds a
1116
+ scheduled wake (a permission prompt, a question) or while the provider
1117
+ says a prompt is open: `E_SESSION_PROMPT_OPEN`. A notice the provider
1118
+ queued is no resume: `E_SESSION_INPUT_QUEUED`. In both cases the home stays
1119
+ as it was, and a later sweep tries again.
1120
+
1121
+ The sweep's rows for provider homes carry `backend`.
1122
+
1123
+ **Other machines and older kernels.** A routed `--backend <provider>`
1124
+ (`--server`) is sent only to a host that lists `session-providers`; another
1125
+ host is refused `E_REMOTE_INCOMPATIBLE` before anything is sent. A kernel
1126
+ without the feature that meets a provider home on the same machine (the
1127
+ Desktop bundles its own kernel) only refuses: every session verb answers
1128
+ `E_RUNTIME_ENDPOINT_UNKNOWN` before any tmux call, a start of a home that
1129
+ was never launched answers `E_LAUNCH_RECIPE_UNSUPPORTED`, and its stop and
1130
+ its retire are refused. Use a kernel that lists the feature for such a home.
1131
+
926
1132
  ### Herdr (removed in 0.31.0)
927
1133
 
928
1134
  OATS no longer supports Herdr. Everything that meets it refuses with
@@ -955,7 +1161,7 @@ saved route that records `herdrPath` still loads; the field is ignored.
955
1161
  | `oats spawn <soul> [--no-launch]` | Creates the home and launches the harness. `--no-launch` creates the home only. |
956
1162
  | `oats session start --home <abs>` | Starts a stopped or never-launched instance again in its existing home. |
957
1163
  | `oats session start --resume --home <abs>` | Starts an instance whose session was lost again, in its own last conversation ([Resume after a shutdown](#resume-after-a-shutdown)). |
958
- | `oats session resume [--deployment <dir>] [--plan]` | Resumes every lost session of this machine's deployments ([Resume after a shutdown](#resume-after-a-shutdown)). |
1164
+ | `oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]]` | Resumes every lost session of this machine's deployments ([Resume after a shutdown](#resume-after-a-shutdown)). |
959
1165
  | `oats session restart --home <abs>` | Stops the running harness and starts it again in place. |
960
1166
  | `oats instance stop <instance> --plan` / `--apply` | Stops the harness and keeps home, work and launch recipe. |
961
1167
  | `oats retire <instance>` | Ends the session and retires the instance ([souls-and-instances.md](souls-and-instances.md#retire)). |
@@ -25,6 +25,17 @@ with read access to the repositories below (your own credential helpers; the
25
25
  kernel never prompts), tmux, and an authenticated harness (Pi, Claude or
26
26
  Codex).
27
27
 
28
+ Node 18 and 20 get
29
+ `E_NODE_UNSUPPORTED` before any command runs, including `version` and
30
+ capability commands. With `--json` the refusal is one failure envelope on
31
+ stdout and exit 1; without it the message is on stderr. A Node too old to
32
+ parse the entry (for example Node 12) can fail with a SyntaxError first.
33
+ The npm package declares `engines.node: ">=22.5.0"` so npm warns at install time.
34
+
35
+ Git 2.45 or later recommended (partial caches); an older Git works, with
36
+ whole-tree fetches. `oats doctor` reports the version and cache support as
37
+ information, without refusing an older Git.
38
+
28
39
  ```bash
29
40
  npm install -g @awebai/oats@latest
30
41
  node --version && tmux -V && oats version --json # features must list workspace-v2