@awebai/oats 0.69.22 → 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 (98) hide show
  1. package/bin/oats.mjs +185 -38
  2. package/docs/capabilities.md +365 -7
  3. package/docs/capability-manifest.schema.json +37 -1
  4. package/docs/configuration.md +27 -7
  5. package/docs/container.md +206 -228
  6. package/docs/design/2026-11-19-sandboxes.md +1352 -0
  7. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  8. package/docs/design/README.md +7 -0
  9. package/docs/desktop-cli-api.md +673 -81
  10. package/docs/desktop.md +241 -65
  11. package/docs/execution-targets.md +186 -3
  12. package/docs/first-team.md +11 -0
  13. package/docs/implementation.md +6 -2
  14. package/docs/integrations.md +3 -3
  15. package/docs/knowledge-capability-authoring.md +10 -7
  16. package/docs/knowledge-reference/acceptance.md +21 -19
  17. package/docs/knowledge-reference/adoption.md +18 -4
  18. package/docs/knowledge-reference/model.md +11 -9
  19. package/docs/knowledge-reference/package-craft.md +2 -2
  20. package/docs/knowledge-reference/proposal.md +127 -0
  21. package/docs/knowledge-reference/provider-mapping.md +10 -10
  22. package/docs/knowledge-reference/reader-capture.md +26 -22
  23. package/docs/knowledge-theory.md +1 -1
  24. package/docs/knowledge.md +25 -16
  25. package/docs/official-catalog.md +4 -4
  26. package/docs/packages.md +13 -13
  27. package/docs/release-notes/v0.69.23.md +231 -0
  28. package/docs/release-notes/v0.69.24.md +264 -0
  29. package/docs/servers.md +10 -6
  30. package/docs/souls-and-instances.md +96 -22
  31. package/docs/tui.md +25 -4
  32. package/docs/upgrading.md +19 -5
  33. package/docs/workspaces.md +14 -6
  34. package/lib/argv.mjs +6 -2
  35. package/lib/capability-contract.mjs +2 -2
  36. package/lib/capability-show.mjs +11 -1
  37. package/lib/command-flags.mjs +40 -3
  38. package/lib/compile-cache.mjs +1 -1
  39. package/lib/core.mjs +1201 -195
  40. package/lib/errors.mjs +4 -1
  41. package/lib/hook-env.mjs +106 -0
  42. package/lib/host-run.mjs +11 -3
  43. package/lib/instance-board.mjs +337 -0
  44. package/lib/instance-events.mjs +48 -10
  45. package/lib/instance-inspect.mjs +44 -0
  46. package/lib/instance-lifecycle.mjs +34 -18
  47. package/lib/instance-listing.mjs +113 -16
  48. package/lib/instance-related-work.mjs +143 -0
  49. package/lib/kernel-features.mjs +13 -1
  50. package/lib/node-version.mjs +9 -0
  51. package/lib/provider-call-child.mjs +60 -0
  52. package/lib/provider-resume.mjs +83 -0
  53. package/lib/provider-test-seams.mjs +20 -0
  54. package/lib/read-call.mjs +2 -0
  55. package/lib/reserved-launch-env.mjs +8 -1
  56. package/lib/retire-admission.mjs +5 -1
  57. package/lib/schedule.mjs +14 -4
  58. package/lib/servers.mjs +151 -17
  59. package/lib/session-inspect.mjs +104 -13
  60. package/lib/session-providers.mjs +528 -0
  61. package/lib/session-resume.mjs +68 -15
  62. package/lib/stable-node.mjs +3 -0
  63. package/lib/triggers.mjs +3 -1
  64. package/package-catalog.json +3 -3
  65. package/package.json +2 -1
  66. package/packages/client/capability-list.mjs +21 -0
  67. package/packages/client/cli-adapter.mjs +19 -4
  68. package/packages/client/cli-locator.mjs +5 -1
  69. package/packages/client/deployment-data.mjs +27 -3
  70. package/packages/client/deployment-panel.mjs +27 -4
  71. package/packages/client/home-board.mjs +33 -19
  72. package/packages/client/inspect-boundary.mjs +18 -8
  73. package/packages/client/instance-acts.mjs +30 -3
  74. package/packages/client/instance-board.mjs +206 -0
  75. package/packages/client/instance-presentation.mjs +55 -0
  76. package/packages/client/instance-tree.mjs +34 -4
  77. package/packages/client/keymap.mjs +5 -0
  78. package/packages/client/liveness.mjs +15 -4
  79. package/packages/client/mail-contract.mjs +130 -0
  80. package/packages/client/own-codes.mjs +5 -1
  81. package/packages/client/panel-views.mjs +7 -7
  82. package/packages/client/related-work.mjs +84 -0
  83. package/packages/client/remote-roster.mjs +9 -3
  84. package/packages/client/session-backends.mjs +31 -0
  85. package/packages/client/session-start.mjs +18 -6
  86. package/packages/client/spawn-apply-cli.mjs +5 -3
  87. package/packages/client/spawn-apply-contract.mjs +25 -2
  88. package/packages/client/spawn-apply.mjs +5 -1
  89. package/packages/client/spawn-messages.mjs +3 -0
  90. package/packages/client/terminal-contract.mjs +4 -0
  91. package/packages/client/waiting-on-you.mjs +12 -2
  92. package/packages/client/workspace-cli.mjs +13 -2
  93. package/packages/tui/lib/model.mjs +14 -3
  94. package/packages/tui/lib/store.mjs +12 -3
  95. package/skills/oats-getting-started/SKILL.md +11 -8
  96. package/docs/knowledge-reference/harvester.md +0 -109
  97. package/lib/instance-same-work.mjs +0 -67
  98. package/packages/client/same-work.mjs +0 -49
@@ -0,0 +1,320 @@
1
+ # The launch state machine of a provider home
2
+
3
+ Status: design of record for the lifecycle of a home on a session provider
4
+ ([execution-targets.md](../execution-targets.md#session-providers),
5
+ [capabilities.md](../capabilities.md#session-providers-sessionproviders)).
6
+ Decided 2026-11-20. The tests in `test/session-provider-lifecycle.test.mjs`
7
+ follow the tables below: one test per cell of "The verbs, by state", one per
8
+ crossing, and one per point between two writes at which the kernel can die
9
+ (it is killed there, by a seam, and the records it leaves are checked).
10
+ `test/session-provider-explorer.test.mjs` goes over what the tables do not
11
+ list one by one: for each verb, the kernel ends at each seam it passes (each
12
+ point between two writes, and each provider call: before, during, after),
13
+ then another verb runs, then an input, against a provider that has sessions;
14
+ and the invariants below are checked once everything has settled. In the
15
+ suite it runs a seeded sample, in seconds; `npm run test:provider-lifecycle`
16
+ runs every schedule (minutes). Pull-request CI runs every schedule, as a job
17
+ of its own that the gate requires, for a change that touches the lifecycle
18
+ (the files `scripts/provider-lifecycle-changed.mjs` lists: this page, the
19
+ code and the tests named here, the workflow), and a nightly run does on
20
+ main.
21
+
22
+ **The invariants.** (1) No session runs that no record names. (2) A home
23
+ recorded planned has no session; one recorded stopped has none but the one
24
+ its record names, and not that one either once a stop of it was confirmed.
25
+ (3) No home is left that no verb can act on: every verb answers a kernel
26
+ code, and a retire takes the home. (4) No input is delivered after a stop
27
+ was confirmed. (5) A home whose start, restart or resume was answered, or
28
+ whose input was submitted, has the session its record names running: nothing
29
+ a kernel left behind stops it afterwards.
30
+
31
+ A provider runs the session; **OATS decides what state the home is in, from
32
+ its own records alone**. The provider is asked only what a record cannot say
33
+ (is the session there, is it running) and is told what to do. This page says
34
+ which records exist, which states they spell, what each verb does in each
35
+ state, in what order it writes, and what happens when two things cross.
36
+
37
+ ## The records
38
+
39
+ | Record | Where | Who can write it | What it holds |
40
+ |---|---|---|---|
41
+ | **Receipt** | `<instances>/.oats-retirement/baselines/<hash of the home>.json`, `runtime` | the kernel; outside the home | the authority: `launched`, `backend`, `provider`, `endpoint`, `stoppedAt`, `launchSent` |
42
+ | **Record** | `<home>/instance.json` | the kernel; inside the home, so the agent can | a copy for readers: `launched`, `backend`, `session {provider, endpoint}`, `startId` |
43
+ | **Stop receipt** | `<home>/.oats-stop.json` | the kernel; inside the home | which stop the last one was, for the current `startId`: an operator's, or the host's (`resume: true, reason: "host-stop"`) |
44
+ | **Claim** | `<instances>/.oats-retirement/claims/<name>.lock` | the kernel; outside the home | which lifecycle verb acts on the home now, and its process |
45
+ | **Resume count** | `OATS_HOME_DIR/session-resume/provider-resumes/<hash>.json` | the kernel; outside the home | the resumes of the last hour, this boot |
46
+ | **Provider call in flight** | `<instances>/.oats-retirement/provider-calls/<name>/<verb>-<pid>-<id>.json`, and `….json.group` | the kernel (the `.group` file: the leader of the process group the provider's command runs in); outside the home | a launch, an input or a stop is being sent for the home now: by which kernel process, and in which process group the provider's command runs |
47
+
48
+ The receipt decides. The record must agree with it
49
+ (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise), **except while the receipt says a
50
+ launch is unsettled** (`launchSent`): then the record's `launched`,
51
+ `session.endpoint` and `startId` are not compared, because the launch that
52
+ would have written them may have ended at any point.
53
+
54
+ ## The states
55
+
56
+ A state is what the receipt says. `E` is an endpoint, `t` an instant.
57
+
58
+ | State | Receipt `runtime` | Record | Meaning |
59
+ |---|---|---|---|
60
+ | **planned** | `{launched: false, backend, provider}` | `launched: false`, `session.endpoint: null` | never launched; no session exists |
61
+ | **sent** | `{launched: true, backend, provider, launchSent: t}` (no endpoint) | `launched: true` (not compared) | a first launch was sent; its outcome is not recorded |
62
+ | **running** | `{launched: true, …, endpoint: E, stoppedAt: null}` | `launched: true`, `session.endpoint: E`, `startId` | OATS started a session at `E` and has not stopped it |
63
+ | **stopped** | `{…, endpoint: E, stoppedAt: t}` | as running | OATS stopped it. The stop receipt says which stop: **operator** (stays down) or **host** (a resume brings it back) |
64
+ | **resent** | `{…, endpoint: E, stoppedAt: t or null, launchSent: t2}` | (not compared) | a launch was sent for a home launched before; its outcome is not recorded |
65
+
66
+ Two things are not states of the records:
67
+
68
+ - **lost**: the records say *running* and the provider says the session is
69
+ gone. Only an inspect tells; nothing is written. A lost session is resumed
70
+ through `input`, under the home's cap.
71
+ - **retiring**: any state, with the claim held by a retire. It ends with the
72
+ home removed.
73
+
74
+ *sent* and *resent* are the **unsettled** states: a session may run that no
75
+ record names. A launch in progress and a launch whose command died look the
76
+ same to a read; the claim tells them apart for a verb (a live holder is busy;
77
+ a dead one is taken over).
78
+
79
+ **The older kernel.** A kernel from before session providers refuses every
80
+ verb on a home whose receipt says `launched: true` without a tmux endpoint,
81
+ a retire included, and would retire a `launched: false` home as never
82
+ launched. That is why *sent* says `launched: true` in the receipt and in the
83
+ record, though no session is known to exist.
84
+
85
+ ## Settling
86
+
87
+ An unsettled home is settled by one procedure, used by every verb that acts
88
+ on it (stop, start, restart, retire), under that verb's claim:
89
+
90
+ 1. Ask the provider: `stop {home, endpoint: null, launchSent: t}`: stop
91
+ whatever session rooted at this home was created at or after `t`.
92
+ 2. Not confirmed: `E_SESSION_STOP_FAILED`; the state is unchanged, and the
93
+ next verb asks again. (A retire goes on all the same when no process works
94
+ in the home, with a warning that names the provider's own tooling: it
95
+ never strands a home on a provider that does not answer.)
96
+ 3. Confirmed: no session of that launch runs. The record is rewritten to
97
+ agree with what the receipt will say, then the receipt:
98
+ - from *sent* → **planned** (record `launched: false`, `endpoint: null`);
99
+ - from *resent* → **stopped** (record `launched: true`, `endpoint: E`;
100
+ receipt `stoppedAt` set if it was null, `launchSent` removed; the stop
101
+ receipt as an operator's, unless it already says the host's).
102
+
103
+ *resent* settles to *stopped*, never to *running*. Step 1 does not reach the
104
+ session at `E`: it is older than the launch (a start of a lost home stops it
105
+ only after its mark, and may have died before). So **every verb that settles
106
+ a resent home asks `stop {endpoint: E}` first**, and settles only once that
107
+ is confirmed: then neither the old session nor the new launch's runs. Not
108
+ confirmed, the home is not settled, whichever verb asked (a retire, which
109
+ removes the home, asks for both stops all the same and records nothing).
110
+
111
+ ## A launch (spawn's, start's, restart's)
112
+
113
+ Always the same steps, under the home's claim (`start`; a spawn takes it
114
+ before its home can be acted on):
115
+
116
+ | # | Step | Record written | State after |
117
+ |---|---|---|---|
118
+ | 1 | What can refuse: the plan, the launch hooks, the provider's `check` with the planned launch. (Three checks run right before step 4: the home's roots, the kernel's shim, the host run's admission. One that refuses there leaves the home as it then is: stopped by step 3, or as before the verb) | none | unchanged |
119
+ | 2 | If unsettled: for a home launched before, the provider's `stop {endpoint: E}` (not confirmed: `E_SESSION_STOP_FAILED`); then settle | see Settling | planned or stopped |
120
+ | 3 | If launched before: stop the session at `E`. A restart of *running* whose session is there records `stoppedAt` and the stop receipt first (the stop rule). A start or a restart of *stopped* asks the provider's `stop {endpoint: E}` again; not confirmed is `E_SESSION_STOP_FAILED`, nothing started. (*Running* whose session is gone: step 4) | receipt, stop receipt (a restart of a session that is there) | stopped, or running-and-gone |
121
+ | 4 | **Mark**: receipt `launchSent: t` (and `launched: true` from planned), then the record's `launched: true` from planned. Then, for *running* whose session is gone, the provider's `stop {endpoint: E}`, and nothing is recorded of it (so a stop that is not confirmed leaves a lost home lost, not stopped as by an operator): not confirmed is `E_SESSION_STOP_FAILED`, the mark taken back (6b), nothing started. After the mark, because an input holds no claim: see the crossings | receipt, then record | sent or resent |
122
+ | 5 | The provider's `launch` | none | sent or resent |
123
+ | 6a | It answered `E'`: receipt `endpoint: E'`, `stoppedAt: null`, **`launchSent` kept**; then the record (`launched: true`, `endpoint: E'`, new `startId`); then the receipt's `launchSent` removed (a spawn removes it at its end, after its lineage is committed, so that no input is admitted to a home whose spawn may still be undone; and only then does a keyed spawn's record say it completed, so a same-key retry never replays an unsettled home as finished) | receipt, record, receipt | running at `E'` |
124
+ | 6b | It refused (nothing was started): **unmark**: record, then receipt | record, then receipt | as before step 4 |
125
+ | 6c | Its answer was lost: settle | see Settling | planned or stopped; or unchanged when the stop is not confirmed |
126
+
127
+ A launch killed at any point after step 4 and before the last write of 6a
128
+ leaves an unsettled home: the next verb settles it. There is no point at
129
+ which the receipt names a session the record contradicts, or at which a
130
+ session runs that the receipt does not account for with either an endpoint
131
+ or `launchSent`.
132
+
133
+ A spawn writes its home's receipt, as planned, BEFORE it publishes the
134
+ record, and again after it; so a spawn that ends between the two leaves a
135
+ planned home, never a record without a receipt, and a spawn that reuses the
136
+ name of a retired home (whose receipt a retire keeps, by its path) is never
137
+ paired with that one. A spawn that fails after step 4 undoes itself: 6b or
138
+ 6c (its fence first: the launch's mark, written again if it was gone
139
+ already; then the drain, as for every stop), then the home is removed. A home it keeps for another debt after a stop that was confirmed (a
140
+ hook's cleanup is owed) is left planned, record and receipt alike, with its
141
+ rollback marker. When the stop of 6c is not confirmed the home is retained,
142
+ unsettled, with its rollback marker. A retire of a retained provider home
143
+ reads the launch from its receipt and record, never from the marker.
144
+
145
+ ## The verbs, by state
146
+
147
+ `—` means the provider is not called.
148
+
149
+ | Verb (claim) | planned | sent | running | stopped | resent |
150
+ |---|---|---|---|---|---|
151
+ | **inspect**, **status** (none) | not launched; — | unknown (`E_SESSION_UNAVAILABLE`; row `unreachable`); — | the provider's `inspect`; unknown when it fails; gone reads *lost* | stopped; — | unknown; — |
152
+ | **input** (none) | `E_SESSION_NOT_RUNNING`; — | `E_SESSION_NOT_RUNNING`; — | `inspect`, then `input` (below) | `E_SESSION_NOT_RUNNING`; — | `E_SESSION_NOT_RUNNING` when `stoppedAt` is set, else `E_SESSION_INPUT_FAILED`; — |
153
+ | **stop** (`stop`) | nothing to stop | settle → planned; answers stopped | the stop rule → stopped | operator's: asks `stop {E}` again, and takes a host's stop as its own. Host's: nothing | as of *running* or of *stopped* by its `stoppedAt` (the stop rule, or `stop {E}` again), then settle → stopped; answers stopped |
154
+ | **start** (`start`) | launch | settle, launch | `inspect`: there → `E_SESSION_RUNNING` or `E_SESSION_UNKNOWN`; gone → launch | launch | `stop {E}`, settle, launch |
155
+ | **restart** (`start`) | launch | settle, launch | `inspect` (unknown refuses): there → the stop rule, launch; gone → launch | launch | `stop {E}`, settle, launch |
156
+ | **resume** (`resume`) | `E_RESUME_NOT_LOST` | `E_SESSION_UNKNOWN` | gone → count, then `input` (the notice); there → `E_SESSION_RUNNING` / `E_RESUME_NOT_LOST` | host's stop → `input` (the notice), then `stoppedAt` cleared, then the stop receipt removed → running; operator's → `E_RESUME_NOT_LOST` | `E_SESSION_UNKNOWN` |
157
+ | **retire** (`retire`) | remove | settle, scan, remove | the stop rule, scan, remove | `stop {E}` again, scan, remove | the stop rule, settle, scan, remove |
158
+
159
+ **The stop rule: fence, drain, stop.** Every stop the kernel asks of a
160
+ provider, whatever the verb, is made by one function, in this order:
161
+
162
+ 1. The **fence**: the record from which no new input is admitted. For a stop
163
+ of a *running* home (stop, restart, retire, the host's shutdown): an
164
+ earlier stop's receipt is removed (one a resume that died left names this
165
+ same start, and would make this stop the host's), then receipt
166
+ `stoppedAt: t`, then the stop receipt. For a launch: its mark. A home
167
+ that is stopped or unsettled already has its fence. A fence that cannot
168
+ be written refuses the verb before the provider is asked, a retire too:
169
+ without it an input is still admitted.
170
+ 2. The **drain** of the provider calls recorded for the home (see "A
171
+ provider's command outlives the kernel that ran it"): an input that is
172
+ being sent is waited for, at most an input's timeout and a margin (about
173
+ 25 s), and ended if it outlasts that or if its kernel is gone.
174
+ 3. The provider's `stop {endpoint: E}`.
175
+
176
+ A stop the provider confirms is therefore final: nothing admitted before the
177
+ fence is still on its way. Not confirmed is `E_SESSION_STOP_FAILED` (a
178
+ retire goes on when no process works in the home, with a warning), and the
179
+ home is *stopped* all the same: from the fence on, input is refused whatever
180
+ the provider does. The cost is the wait of step 2, while an input is in
181
+ flight.
182
+
183
+ **Scan** (a retire): no process may work in the home after the provider's
184
+ stop, confirmed or not.
185
+
186
+ **A resume's notice that fails.** Refused by the provider (a prompt is open,
187
+ it was queued): nothing was sent; a lost session's count is given back, and a
188
+ home stopped with the host stays so, still to resume. Failed otherwise: the
189
+ provider may have restarted the session on it; a lost session's count stays,
190
+ and for a home stopped with the host, which stays stopped, the provider is
191
+ asked `stop {E}` again.
192
+
193
+ **Input to a running home**: `inspect`; gone is a lost session, whose input
194
+ is a resume (counted before the provider is called, refused at the cap);
195
+ then the record is read again, `input` is sent, and the record is read once
196
+ more (the crossing check, below).
197
+
198
+ ## Crossings
199
+
200
+ **A verb arrives while another holds the claim.** Stop, start, restart,
201
+ resume and retire take the claim; a second one is refused as busy
202
+ (`E_LIFECYCLE_BUSY`, `E_SESSION_START_BUSY`, …) before any effect. A spawn
203
+ of a provider home, launched or not, holds the claim from before its home is *planned* on disk until its last
204
+ write of the home's record (after its launch is recorded) or until its
205
+ launch is undone, so the home is never acted on while it launches, and no
206
+ verb's record is overwritten by the spawn's.
207
+ Reads (inspect, status, the plans) take no claim: they answer the state the
208
+ records spell at that instant, which during a launch is *sent* or *resent*,
209
+ that is, unknown.
210
+
211
+ **The holder died.** A claim names its holder by process id and that
212
+ process's start time. A holder is gone when no process has that id, or the
213
+ one that has it started at another time (the id was reused), or it is a
214
+ zombie; a holder whose liveness cannot be read is not gone, and the verb is
215
+ refused as busy. The next verb takes over a gone holder's claim. The records
216
+ are in one of the states above whatever the point of death, by the write
217
+ orders of "A launch" and of the stop rule:
218
+
219
+ | Died | State left | The next verb |
220
+ |---|---|---|
221
+ | before the mark (step 4) | as before the verb | acts on it |
222
+ | between the mark's two writes | sent, record `launched: false` (not compared) | settles |
223
+ | during the provider's launch, or after its answer and before the last write of 6a | sent or resent; a session may run | settles: the provider stops it by home and `launchSent` |
224
+ | during the stop rule, after `stoppedAt` | stopped (as an operator's until the stop receipt is written, then as the stop's own); the provider may not have been asked | a stop or a start asks `stop {E}` again |
225
+ | during a settle, after the provider confirmed | unsettled still, or settled | settles again (the provider's stop is idempotent), or acts |
226
+ | during a launch the provider refused, between the record and the receipt of its unmarking | sent | settles (there is nothing to stop) |
227
+ | during a spawn, after its launch's outcome and before its last write of the record | resent (the mark is kept to that write) | settles: `stop {E}`, then the launch's; the home is stopped |
228
+ | during a spawn's rollback, between its record and its receipt | unsettled: the launch still marked, the record already planned (not compared) | settles |
229
+ | during a spawn, between the planned record and its last receipt | planned (the receipt was written before the record) | acts on it |
230
+ | during a resume of a home stopped with the host, after its notice | stopped with the host; its session may run again | the sweep sends the notice again; a stop or a start asks `stop {E}` |
231
+ | during that resume, after `stoppedAt` was cleared | running, with the host's stop receipt left | acts on a running home; a later loss of that start is a loss like any other, counted (a stop receipt says the host's stop only beside a receipt that says stopped), and a later stop removes that receipt before it records its own |
232
+
233
+ **An input in flight across a state change.** An input holds no claim and a
234
+ provider restarts a session on it, so the kernel checks after the send, with
235
+ one read of the home, whatever the provider answered (a refusal included):
236
+
237
+ | What the read says | What happened | What the kernel does |
238
+ |---|---|---|
239
+ | running, the same `startId` and endpoint | nothing | answers the provider's answer |
240
+ | stopped, or no session recorded | a stop landed, or a retire is waiting for this input (below) | `stop {E}` again; `E_SESSION_NOT_RUNNING`, not delivered |
241
+ | unsettled | a start is launching | `stop {E}` again; `E_SESSION_NOT_RUNNING`, not delivered |
242
+ | running, another `startId`, another endpoint | a restart landed | `stop {E}` again (the old one); `E_SESSION_NOT_RUNNING` |
243
+ | running, another `startId`, the same endpoint | a restart landed, and the provider reused the locator, which it must not (below) | nothing is stopped (that locator is the new session's); `E_SESSION_NOT_RUNNING`. The provider may have delivered the input to the new session all the same: the mail stays unread and is presented again, a duplicate, never a loss |
244
+
245
+ Since every stop drains (the stop rule), a stop's and a restart's own stop
246
+ wait for the input, which then reads the home *stopped*: the two rows
247
+ "running, another `startId`" are reached only by an input that outlasted the
248
+ drain's wait: its provider call is ended there, and its kernel, still
249
+ running, reads the home after the restart recorded its launch.
250
+
251
+ The same read before the send refuses without sending. A start of a lost
252
+ home stops the session at `E` after its mark (step 4), which covers the
253
+ input that finished before the mark: its provider call had ended by then, so
254
+ the session it restarted at `E` is stopped before the new one is launched,
255
+ and an input that reads the home after the mark stops it itself (the row
256
+ "unsettled").
257
+
258
+ A provider that hands a launch an endpoint it used before for the home
259
+ breaks the rule below. In the rows "stopped" and "unsettled" the `stop {E}`
260
+ then addresses whatever session holds that locator by then, which can be the
261
+ new one: the home is recorded running, its session is gone, it reads lost,
262
+ and the next input resumes it.
263
+
264
+ **The drain, and an input in flight.** An input holds no claim, so one can
265
+ be on its way when a stop, a start or a retire writes its fence. After a
266
+ stop or a restart the input itself could still ask the provider to stop
267
+ again (the table above); after a retire it could not: the home, and the
268
+ provider's commands with it, are gone; and an input whose kernel is killed
269
+ asks for nothing. So an input records that it is in flight, outside the
270
+ home, before its read of the home and until its answer, and **every stop
271
+ drains before it asks the provider**: it waits for the inputs in flight to
272
+ end, at most an input's timeout and a margin; one whose kernel is gone, or
273
+ dies meanwhile, is ended at once (below); one still in flight at the bound
274
+ is ended too (a retire then says so, naming the input's process).
275
+
276
+ **A provider's command outlives the kernel that ran it.** The kernel runs
277
+ every command of a provider in a process group of its own. A kernel that is
278
+ killed while it waits for one leaves that command running: a launch that
279
+ creates its session later, an input that restarts one, a stop that stops a
280
+ session resumed since. So a launch, an input and EVERY stop the kernel sends
281
+ (one function sends them all: a verb's, a spawn's rollback, an input's own
282
+ after a crossing) are recorded while they run (the table at the top: the kernel that made the
283
+ call, and the group its command runs in, written by the group's leader
284
+ before the provider runs), and the record is removed when the call returns.
285
+
286
+ A record whose kernel is gone is a call that may still act. The kernel
287
+ **ends** it: the group is killed (SIGKILL) and seen empty. A call whose
288
+ group had not recorded itself yet is made void: the kernel creates the
289
+ group's file itself, removes the call's record, then that file (both the
290
+ leader and the kernel publish that file whole, by an exclusive link from a
291
+ file of their own, so neither ever finds it half written); a leader
292
+ that comes late finds the file, or finds its call's record gone, and runs
293
+ nothing. A group that cannot be ended (its leader is gone and members are
294
+ left, or they survive) refuses the verb: `E_SESSION_STOP_FAILED` for a stop,
295
+ and an unsettled home stays unsettled.
296
+
297
+ Such calls are ended **before a provider's stop is relied on** (the drain),
298
+ and **before a launch, an input or a resume's notice is sent** (a stop left
299
+ behind would run late and stop what they start).
300
+
301
+ One window stays: a request the provider's own server had accepted before
302
+ the group was killed can complete moments later. The provider's `stop`,
303
+ which the kernel sends after the group is gone, is what covers it.
304
+
305
+ **Resume count.** Taken under its own lock, before the provider's `input`,
306
+ and given back only when the provider itself refused the input.
307
+
308
+ ## What a provider must do for this to hold
309
+
310
+ - `stop` is idempotent, and with `endpoint: null` stops whatever session
311
+ rooted at the home was created at or after `launchSent`.
312
+ - `launch` either answers an endpoint for a session it started, or refuses
313
+ having started nothing. **The endpoint it answers differs from every
314
+ endpoint it answered before for that home**: an endpoint names one session,
315
+ never a place that a later session takes over.
316
+ - `input` answers `submitted: true` only when it dispatched the input.
317
+ - A command runs its own helpers inside the process group the kernel runs
318
+ it in, and never detaches them: ending the group ends everything the
319
+ command would still do on this host. Its `stop` looks at what is there
320
+ when it is asked, after that group is gone.
@@ -26,10 +26,17 @@ successor, with a link to its full text.
26
26
  a stopped home's package modules to the locked versions, with plan, apply,
27
27
  provider adoption and undo (supersedes workspace model v2 items 10–11 for
28
28
  package modules).
29
+ - [The launch state machine of a provider home](2026-11-20-provider-home-lifecycle.md):
30
+ the records, the states, what each lifecycle verb does in each, and the
31
+ crossings, for a home on a session provider.
29
32
  - [The warm reader](2026-10-29-warm-reader.md): `oats reader --stdio`, a
30
33
  child the Desktop and the TUI start, answers `oats status` and `oats
31
34
  workspace status` with the kernel's own read code kept loaded: warm code,
32
35
  not warm data, the same answers as the CLI, and the CLI as the fallback.
36
+ - [Sandboxes](2026-11-19-sandboxes.md) (contracts decided, amended in r5, not
37
+ built): boundaries declared in the workspace's `sandboxes:`, each listing the souls
38
+ it may run, started by `oats sync` on the machines that list them. Placement no
39
+ longer follows a team (r5).
33
40
 
34
41
  The Desktop's design brief for designers is in
35
42
  [packages/desktop/docs](../../packages/desktop/docs/design-brief.md).