@awebai/oats 0.69.23 → 0.69.24

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 (74) hide show
  1. package/bin/oats.mjs +56 -17
  2. package/docs/capabilities.md +353 -5
  3. package/docs/capability-manifest.schema.json +36 -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 +320 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +257 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +186 -3
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +5 -1
  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/souls-and-instances.md +45 -0
  21. package/docs/tui.md +21 -1
  22. package/docs/upgrading.md +12 -5
  23. package/docs/workspaces.md +13 -5
  24. package/lib/capability-show.mjs +11 -1
  25. package/lib/command-flags.mjs +2 -2
  26. package/lib/compile-cache.mjs +1 -1
  27. package/lib/core.mjs +1176 -181
  28. package/lib/errors.mjs +4 -1
  29. package/lib/hook-env.mjs +106 -0
  30. package/lib/host-run.mjs +11 -3
  31. package/lib/instance-inspect.mjs +44 -0
  32. package/lib/instance-lifecycle.mjs +15 -3
  33. package/lib/instance-listing.mjs +97 -8
  34. package/lib/kernel-features.mjs +10 -1
  35. package/lib/node-version.mjs +9 -0
  36. package/lib/provider-call-child.mjs +60 -0
  37. package/lib/provider-resume.mjs +83 -0
  38. package/lib/provider-test-seams.mjs +20 -0
  39. package/lib/read-call.mjs +2 -0
  40. package/lib/reserved-launch-env.mjs +8 -1
  41. package/lib/retire-admission.mjs +5 -1
  42. package/lib/schedule.mjs +14 -4
  43. package/lib/servers.mjs +28 -4
  44. package/lib/session-inspect.mjs +104 -13
  45. package/lib/session-providers.mjs +528 -0
  46. package/lib/session-resume.mjs +68 -15
  47. package/lib/stable-node.mjs +3 -0
  48. package/lib/triggers.mjs +3 -1
  49. package/package-catalog.json +2 -2
  50. package/package.json +2 -1
  51. package/packages/client/capability-list.mjs +21 -0
  52. package/packages/client/cli-adapter.mjs +19 -4
  53. package/packages/client/cli-locator.mjs +5 -1
  54. package/packages/client/deployment-data.mjs +23 -1
  55. package/packages/client/deployment-panel.mjs +25 -3
  56. package/packages/client/home-board.mjs +33 -19
  57. package/packages/client/inspect-boundary.mjs +18 -8
  58. package/packages/client/instance-acts.mjs +30 -3
  59. package/packages/client/instance-board.mjs +206 -0
  60. package/packages/client/instance-presentation.mjs +55 -0
  61. package/packages/client/liveness.mjs +15 -4
  62. package/packages/client/own-codes.mjs +5 -1
  63. package/packages/client/remote-roster.mjs +6 -1
  64. package/packages/client/session-backends.mjs +31 -0
  65. package/packages/client/session-start.mjs +18 -6
  66. package/packages/client/spawn-apply-cli.mjs +5 -3
  67. package/packages/client/spawn-apply-contract.mjs +25 -2
  68. package/packages/client/spawn-apply.mjs +5 -1
  69. package/packages/client/spawn-messages.mjs +3 -0
  70. package/packages/client/terminal-contract.mjs +4 -0
  71. package/packages/client/waiting-on-you.mjs +12 -2
  72. package/packages/tui/lib/model.mjs +14 -3
  73. package/packages/tui/lib/store.mjs +12 -3
  74. 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
@@ -923,6 +927,185 @@ other instance whose window is in that session, not only the one you are
923
927
  moving. And a window that a viewer still links would live on in that viewer,
924
928
  so the next start would create a second window for the same home.
925
929
 
930
+ ### Session providers
931
+
932
+ A kernel that lists the feature `session-providers` (`oats version --json`)
933
+ can run an instance on a session backend that a capability supplies: the
934
+ agent runs where the provider runs it, and OATS keeps the instance's home,
935
+ its records, its lifecycle and its answers. What a capability declares and
936
+ answers is in
937
+ [capabilities.md](capabilities.md#session-providers-sessionproviders). tmux
938
+ homes are unchanged.
939
+
940
+ **Selecting one.** `oats spawn <soul> --backend <name>`, a schedule's
941
+ `backend` and a trigger's `spawn.backend` take a provider's name. The
942
+ provider is one that a capability of that instance declares:
943
+ `oats inspect --soul <soul> --json` lists them under `sessionProviders`
944
+ (`[{name, capability}]`), and so does `oats inspect --home`. Refused before
945
+ anything is created, and shown by a spawn preview:
946
+
947
+ | Code | When |
948
+ |---|---|
949
+ | `E_BACKEND_UNKNOWN` | no capability of the instance declares the name, or declares it malformed; the message names the backends available |
950
+ | `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) |
951
+ | `E_BACKEND_HARNESS` | the provider does not run the launch's harness |
952
+ | `E_BACKEND_LAUNCH_ARG` | the launch configuration declares an `executable`: a provider runs the harness itself |
953
+ | `E_BACKEND_NOT_READY` | the provider's own readiness check, asked right before the launch, says it cannot take it |
954
+
955
+ A provider can also refuse the launch with its own `E_BACKEND_*` code (a
956
+ launch environment entry or an argument it cannot carry), which OATS relays;
957
+ the spawn is then rolled back.
958
+
959
+ **What OATS checks for a provider launch, and what it does not.** The launch
960
+ configuration, the harness, the model, yolo, the capabilities' hooks and the
961
+ launch environment are decided as for tmux and handed to the provider. The
962
+ checks about a terminal pane are skipped, because no pane runs the harness:
963
+ the harness executable on the pane's `PATH`, folder trust, the Claude login
964
+ credential, the development-channel prompt, the native-record wrapper. The
965
+ provider's readiness covers what they covered. One check stays: a
966
+ capability's harness-package requirement (`requires`) is probed for a
967
+ provider launch too, on this host, unless the row says which backends it is
968
+ for (`backends: ["tmux"]` leaves it out of a provider launch;
969
+ `["session-provider"]` makes it one of provider launches only).
970
+
971
+ **Records.** A provider home's `instance.json` carries `backend: "<name>"`
972
+ and `session: {provider, endpoint}` (`provider`: the capability; `endpoint`:
973
+ the provider's own locator, at most 4 KiB, `null` before the first launch),
974
+ and no `tmux` and no `command`; its launch recipe's `executable` is `null`.
975
+ Its receipt records `runtime: {launched, backend, provider, endpoint,
976
+ stoppedAt}`. The two must agree as for tmux: `E_RUNTIME_AUTHORITY_MISMATCH`
977
+ otherwise, whose `details.fields` are `backend`, `session.provider` and
978
+ `session.endpoint`.
979
+
980
+ **The lifecycle of a provider home is one state machine**, set out in
981
+ [its design record](design/2026-11-20-provider-home-lifecycle.md): the
982
+ states its records spell, what each verb does in each, in what order it
983
+ writes, and what happens when two things cross. In short:
984
+
985
+ - The receipt's `runtime` carries `launchSent` (an instant) **while a launch
986
+ that was sent to the provider has no recorded outcome**: written right
987
+ before the provider's launch is called, by a spawn and by a start, kept
988
+ until the launch's endpoint is in the receipt *and* in the record, and
989
+ removed last. A launch that is killed leaves it there.
990
+ - Such a home is **unsettled**: a session may run that no record names. It
991
+ reads as unknown (`oats session inspect` answers `E_SESSION_UNAVAILABLE`,
992
+ its status row `running: null`, `runtimeState: "unreachable"`), during a
993
+ launch as after one that died; its record is not compared with its receipt
994
+ meanwhile; input to it is refused, nothing sent.
995
+ - A stop, a start, a restart and a retire **settle** it first: the provider
996
+ is asked to stop whatever session rooted at the home was created since
997
+ that instant (`stop` with `endpoint: null` and `launchSent`). Confirmed, a
998
+ home that was never launched is as it was, and one launched before is
999
+ stopped; not confirmed is `E_SESSION_STOP_FAILED`, and the next verb asks
1000
+ again.
1001
+ - For a home that was **never launched**, the receipt reads `runtime:
1002
+ {launched: true, backend, provider, launchSent}` meanwhile and
1003
+ `instance.json` `launched: true`, both without an endpoint. A kernel from
1004
+ before session providers reads that as a launch it cannot address and
1005
+ refuses every verb on the home, a retire included, where it would have
1006
+ retired a home it read as never launched.
1007
+
1008
+ **The verbs.**
1009
+
1010
+ | Verb | On a provider home |
1011
+ |---|---|
1012
+ | `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" |
1013
+ | `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)) |
1014
+ | `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 |
1015
+ | `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 |
1016
+ | `session restart` | stop, then start, under one lifecycle claim |
1017
+ | `session start --resume` | sends the resume notice through the provider's input; nothing is launched ([below](#provider-homes-lost-sessions)) |
1018
+ | `session attach` | `E_SESSION_NO_TERMINAL`; the message carries inspect's `open` link when there is one |
1019
+ | `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)) |
1020
+
1021
+ **Stop stays stopped.** OATS records `stoppedAt` in the receipt at every stop
1022
+ it makes (`oats instance stop`, a restart's stop, a retire, the host's
1023
+ shutdown), before it calls the provider, and a start clears it. While it is
1024
+ set, inspect answers stopped (`present: false`, `running: false`) without
1025
+ calling the provider, and every input is refused `E_SESSION_NOT_RUNNING`
1026
+ before any call: `oats session input`, a scheduled wake (which never starts
1027
+ a provider home), a client's input, the messaging broker's delivery. A stop
1028
+ that lands while an input is being sent still wins: OATS asks the provider
1029
+ to stop the session again and answers the input `E_SESSION_NOT_RUNNING`, so
1030
+ a mail stays unread and comes again. A
1031
+ session stopped in the provider's own interface sets nothing in OATS, and
1032
+ the provider may restart it on the next input: **stop an OATS agent with
1033
+ OATS**.
1034
+
1035
+ **Status.** A provider home's row of `oats status --json` carries `backend`,
1036
+ `session: {provider}`, `tmux: null`, `open`, `running` (`true`, `false`, or
1037
+ `null` where the provider cannot tell) and `runtimeState`, always set:
1038
+ `unknown`, `shell`, `stopped` or `unreachable` (with `runtimeError`). On the
1039
+ host where the home lives the row's `session` also carries `threadId`, when
1040
+ the provider's endpoint names one, so a tool on that host can match a session
1041
+ to its instance. The endpoint itself is on `oats session inspect --home` and
1042
+ on a spawn's and a start's answer, on that host only: **nothing of it is
1043
+ relayed** by `oats server roster` or `--server`, whose rows and answers carry
1044
+ `session: {provider}`. A tmux row carries `backend: "tmux"`; a row with no
1045
+ `backend` (an older kernel, an older routed host) is a tmux row. Status asks
1046
+ each provider once per group of homes where it can (`inspectMany`), falls
1047
+ back to one `inspect` per home when a batch is bad (never after one that
1048
+ timed out), gives all its providers 30 s together, and asks nothing about a
1049
+ home OATS stopped, which keeps its last endpoint until its next start.
1050
+ `waitingOnYou` is the producers' claim, as for tmux, read while the session
1051
+ is there and not in error.
1052
+
1053
+ <a id="provider-homes-lost-sessions"></a>
1054
+
1055
+ **Lost sessions, and the resume.** An OATS stop is the intent that keeps a
1056
+ home down; only a lost session is resumed, in its own conversation, on the
1057
+ host where the home lives. Two provider homes read `sessionEnd: "lost"`:
1058
+
1059
+ - one stopped by **`oats host run`'s shutdown**. That stop records
1060
+ `stoppedAt` like any other, so input stays refused while the host or the
1061
+ container goes down, and the home's stop receipt says the host's shutdown
1062
+ wrote it. An operator's stop after it withdraws that. The shutdown stops
1063
+ every provider home OATS has not stopped, whatever its session reads, and
1064
+ asks no provider to find them (`oats session resume --plan
1065
+ --without-provider-inspect`), so a provider that goes down with the host
1066
+ cannot hold it up.
1067
+ - one whose session is **gone while OATS did not stop it**: the provider
1068
+ answers `present: false`. A provider reads a session in error this way.
1069
+
1070
+ The sweep (`oats session resume`: the Desktop and the TUI when they open,
1071
+ `oats host run` at its start and each minute) resumes both with `oats session
1072
+ start --resume --home <home>`, which you can also run for one home: it clears
1073
+ the stop, if there is one, and sends one resume notice through the
1074
+ provider's input. Nothing is launched, and a home an operator stopped stays
1075
+ stopped. The rules of that resume:
1076
+
1077
+ - **The cap.** A lost session's resume is counted against the home, at most
1078
+ 3 in an hour within one boot, as the sweep bounds a tmux home's starts. The
1079
+ kernel counts before it calls the provider, and **any input to a lost
1080
+ session is a resume** (a mail the broker delivers, a scheduled wake): the
1081
+ provider would restart the session on it. At the cap the resume and the
1082
+ input are refused `E_SESSION_NOT_RUNNING`, nothing is sent, a mail stays
1083
+ unread, and the sweep's row is `refused`, `keeps-getting-lost`. A stop with
1084
+ the host is no crash and is not counted. A resume the provider itself
1085
+ refuses is not counted either (nothing was sent); one whose call fails is,
1086
+ since the provider may have restarted the session.
1087
+ - **The last run's processes.** A resume of a lost session waits until no
1088
+ process works in the home (a harness can outlive its server's crash), for
1089
+ at most 150 s. Past that it refuses `E_SESSION_UNKNOWN`, names the
1090
+ processes and never kills them; it is not counted, and the next sweep tries
1091
+ again. An input does not wait: it is refused at once.
1092
+ - **The notice is input.** It is not sent while a claim is open that holds a
1093
+ scheduled wake (a permission prompt, a question) or while the provider
1094
+ says a prompt is open: `E_SESSION_PROMPT_OPEN`. A notice the provider
1095
+ queued is no resume: `E_SESSION_INPUT_QUEUED`. In both cases the home stays
1096
+ as it was, and a later sweep tries again.
1097
+
1098
+ The sweep's rows for provider homes carry `backend`.
1099
+
1100
+ **Other machines and older kernels.** A routed `--backend <provider>`
1101
+ (`--server`) is sent only to a host that lists `session-providers`; another
1102
+ host is refused `E_REMOTE_INCOMPATIBLE` before anything is sent. A kernel
1103
+ without the feature that meets a provider home on the same machine (the
1104
+ Desktop bundles its own kernel) only refuses: every session verb answers
1105
+ `E_RUNTIME_ENDPOINT_UNKNOWN` before any tmux call, a start of a home that
1106
+ was never launched answers `E_LAUNCH_RECIPE_UNSUPPORTED`, and its stop and
1107
+ its retire are refused. Use a kernel that lists the feature for such a home.
1108
+
926
1109
  ### Herdr (removed in 0.31.0)
927
1110
 
928
1111
  OATS no longer supports Herdr. Everything that meets it refuses with
@@ -955,7 +1138,7 @@ saved route that records `herdrPath` still loads; the field is ignored.
955
1138
  | `oats spawn <soul> [--no-launch]` | Creates the home and launches the harness. `--no-launch` creates the home only. |
956
1139
  | `oats session start --home <abs>` | Starts a stopped or never-launched instance again in its existing home. |
957
1140
  | `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)). |
1141
+ | `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
1142
  | `oats session restart --home <abs>` | Stops the running harness and starts it again in place. |
960
1143
  | `oats instance stop <instance> --plan` / `--apply` | Stops the harness and keeps home, work and launch recipe. |
961
1144
  | `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
@@ -80,7 +80,7 @@ and the rules its tests pin.
80
80
 
81
81
  | path | contents |
82
82
  |---|---|
83
- | `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs. Its only static imports are Node built-ins and two dependency-free modules, `lib/compile-cache.mjs` and `lib/hot-reads.mjs`: it turns Node's compile cache on first, then imports the kernel and `yaml` with top-level `await import()`, in their order, because static imports are all parsed and linked before a module's body runs. A hot read (`version`, `session inspect`, `status`, `workspace status`, `instance events`, `instance waiting clear`, given only their own flags) imports only the leaves it uses, never `core.mjs` ([`hot-reads.mjs`](#kernel-modules)); every other command imports every module. A hot read takes its names from `lib/hot-reads.mjs`: a name newly used on a hot read's path must be listed there, under its import line, or its first use throws (a tripwire), and `test/cli-hot-reads.test.mjs` pins what each hot read must not load |
83
+ | `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs. Its static imports are Node built-ins and dependency-free startup helpers (`node-version`, `compile-cache`, `hot-reads`, `install-stamp`): its first statement checks the Node 22 floor, before the install stamp or compile cache; then it imports the kernel and `yaml` with top-level `await import()`, in their order, because static imports are all parsed and linked before a module's body runs. A hot read (`version`, `session inspect`, `status`, `workspace status`, `instance events`, `instance waiting clear`, given only their own flags) imports only the leaves it uses, never `core.mjs` ([`hot-reads.mjs`](#kernel-modules)); every other command imports every module. A hot read takes its names from `lib/hot-reads.mjs`: a name newly used on a hot read's path must be listed there, under its import line, or its first use throws (a tripwire), and `test/cli-hot-reads.test.mjs` pins what each hot read must not load |
84
84
  | `lib/` | the kernel (below) |
85
85
  | `injects/` | the kernel and work-mode instruction blocks composed into every instance |
86
86
  | `skills/` | bootstrap skills shipped with the kernel |
@@ -105,6 +105,7 @@ and the rules its tests pin.
105
105
  | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
106
106
  | `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
107
107
  | `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
108
+ | `node-version.mjs` | the CLI startup check and `E_NODE_UNSUPPORTED` envelope for Node before 22, shared with unit tests. No imports or effects; loads on Node 18 and 20 before the install stamp, compile cache or kernel. CI runs the actual CLI on Node 20 (`scripts/check-unsupported-node.mjs`) to prove the refusal precedes every dispatch path |
108
109
  | `compile-cache.mjs` | the CLI's Node compile cache (awebai/oats#1630): `$OATS_HOME_DIR/compile-cache`, made 0700, unless the caller's `NODE_COMPILE_CACHE` or `NODE_DISABLE_COMPILE_CACHE` decides; any failure is no cache and prints nothing, and `NODE_COMPILE_CACHE` is never put in the environment children inherit ([configuration](configuration.md#the-compile-cache)). Node built-ins only; kernel-private, not in `./core` |
109
110
  | `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630), and the warm reader's start (`oats reader --stdio`, whose reads `reader.mjs` imports itself): each one's form (its words and the flags it takes) and, for each import line of `bin/oats.mjs`, the leaves it loads in that line's place; a line it does not list loads nothing, and any other argv loads everything. A name a read does not list is a tripwire: destructuring it is free, and any use throws a `HotReadUnlisted` defect naming the read, the line and the name. `test/cli-hot-reads.test.mjs` runs each read with a load hook and pins what it must not load. Kernel-private, not in `./core` |
110
111
  | `roster-read.mjs`, `workspace-read.mjs`, `read-call.mjs` | the deployment reads (awebai/oats#1630): `oats status` (`roster-read.mjs`: the roster, its drift and its workspace identity) and `oats workspace status` (`workspace-read.mjs`: members, packages, automations, the desktop facts, and the rows `oats sync` reports too), one implementation behind the CLI and a process that answers them many times. Each has an answer function (`statusAnswer`, `workspaceStatusAnswer`: `{ exit, answer, stderr }`, `answer` the JSON the CLI prints, a refusal included) and a data function (`statusView`, `workspaceStatusView`) bin's text renderer reads. `read-call.mjs` is one call's scope: it takes an explicit context (the absolute `dir`, `maxAge`, the caller's read session, the cache, an optional deployments observer), resets at its start every piece of module-level state the reads can reach (`READ_STATE`; `test/read-call-state.test.mjs` scans the reads' import closure and fails on a binding with no row), answers refusals as envelopes, and drains the session's notices. Within one call, two pieces of work are not repeated: `listInstances` hands the records it read to the rest of the read (`records`: `legacyCapturedHomes` and the waiting read take them instead of parsing them again), and `workspace status` asks git for each member clone's remotes once (`remotes`, shared by the automation scope and the desktop facts); both are maps the read makes and drops, never module state. A call registers no process listener, closes no session and reads no argv or cwd: the CLI passes `commandSession` (created at the first remote read, with its exit and signal listeners) and closes it at the end of the command, as for every verb. The read part of the dispatch is there too (`parseMaxAge`, `readBudget`, `callSession`); `test/read-call-equivalence.test.mjs` answers both reads many times in one process and compares each answer with a fresh CLI run's. Leaves: never `core.mjs`. Kernel-private, not in `./core` |
@@ -131,6 +132,9 @@ and the rules its tests pin.
131
132
  | `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: local listings and the sweep recording homes it started; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
132
133
  | `stable-node.mjs` | the one rule for a node path written into anything that outlives the process: the host timer's unit and `OATS_NODE_BIN` ([capabilities](capabilities.md#the-node-a-hook-writes-down)). It imports nothing of the kernel |
133
134
  | `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
135
+ | `session-providers.mjs` | a capability's `sessionProviders` (feature `session-providers`): the use-time validator (per provider, never from the manifest contract or discovery), `--backend`'s selection among an instance's capabilities, the wire (one call of the home's own module copy per verb, with the hook environment) and the rules of each verb's answer, the receipt's `runtime` for a provider home. A leaf: `session-inspect.mjs` and `instance-listing.mjs` call a provider on the hot reads; `core.mjs` holds the launch, stop, start and retire of a provider home. |
136
+ | `hook-env.mjs` | the environment a capability's code runs with in an instance home (`lifecycleHookEnv`, `teamEnv`, `stableSoulId`, `instanceSoulDir`, `kernelBin`): every lifecycle hook's and a session provider's commands'. A leaf, re-exported by `core.mjs`. |
137
+ | `provider-resume.mjs` | the resume cap of a home on a session provider: at most `RESUME_LIMIT` resumes of one home in `RESUME_WINDOW_MS`, in one boot, counted before the provider's input is called (the sweep's notice, `session start --resume`, any input to a lost session). One kernel-private file per home under `OATS_HOME_DIR`. A leaf. |
134
138
  | `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
135
139
  | `host-run.mjs`, `host-run-work.mjs`, `host-run-child.mjs`, `host-run-admission.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep at the start, then the tick and the sweep each minute, every one an owned child group (`host-run-work.mjs`) so that the loop stays free for the signal. On SIGTERM no minute is armed; active work gets 10 s, then the private scratch-file fence is closed and owned groups get 5 s of cancellation. The private bootstrap carries the fence only through kernel child argv, never public flags or environment. A detached kernel group atomically registers its pid/start and waits for the owner to verify it and acknowledge responsibility before importing launch-capable code; cancellation therefore does not depend on an intermediate supervisor remaining responsive. Schedule/trigger loops, resume batches and core launch boundaries read it synchronously, because a synchronous tick cannot service IPC while a command runs. Interrupted attempts remain unknown. The host-run claim stays held until owned work ends. After a final bounded listing, each running home is stopped by a private child of its own (`host-stop-child.mjs`: `core.mjs` `stopInstanceSession` with `withHost`, whose stop record asks for a resume and is written before the signal, read by `session-end.mjs` as `lost`). The clock, the timer, the children and the signal are options, for its tests |
136
140
  | `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v6.3.0
44
- oats.aweb: v1.46.0
44
+ oats.aweb: v1.47.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -97,7 +97,7 @@ operations in full.
97
97
  - **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
98
98
  tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
99
99
  identity in its default team. **An existing workspace opts in** by pinning
100
- `oats.aweb: v1.46.0` (the feature needs 1.31.0 or later), adding
100
+ `oats.aweb: v1.47.0` (the feature needs 1.31.0 or later), adding
101
101
  `tasks: { oats.aweb-tasks: { from: package } }` to `defaults`, and running
102
102
  `oats sync`. Only new spawns get it. A soul that names its own tasks
103
103
  provider in `capabilities:` (`oats.jira`, `oats.linear`) then holds two and