@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
@@ -0,0 +1,322 @@
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
+ | **Composition** | the same receipt, `composition`; and the kernel's own copy of the home's modules, `<instances>/.oats-retirement/modules/<hash of the home>/<store>/` | the kernel (a spawn, and an upgrade's swap); outside the home | what the kernel runs of the home: its own copy of every module, and the home's capability rows (settings, hook commands that name that copy). No verb of this page writes it; every one runs the home's hooks and its provider's commands from it, never from the home ([What the kernel trusts in a provider home](../capabilities.md#what-the-kernel-trusts-in-a-provider-home)). A retire removes the copy with the home |
43
+ | **Record** | `<home>/instance.json` | the kernel; inside the home, so the agent can | a copy for readers: `launched`, `backend`, `session {provider, endpoint}`, `startId` |
44
+ | **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"`) |
45
+ | **Claim** | `<instances>/.oats-retirement/claims/<name>.lock` | the kernel; outside the home | which lifecycle verb acts on the home now, and its process |
46
+ | **Resume count** | `OATS_HOME_DIR/session-resume/provider-resumes/<hash>.json` | the kernel; outside the home | the resumes of the last hour, this boot |
47
+ | **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 |
48
+
49
+ The receipt decides. The record must agree with it
50
+ (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise), **except while the receipt says a
51
+ launch is unsettled** (`launchSent`): then the record's `launched`,
52
+ `session.endpoint` and `startId` are not compared, because the launch that
53
+ would have written them may have ended at any point.
54
+
55
+ ## The states
56
+
57
+ A state is what the receipt says. `E` is an endpoint, `t` an instant.
58
+
59
+ | State | Receipt `runtime` | Record | Meaning |
60
+ |---|---|---|---|
61
+ | **planned** | `{launched: false, backend, provider}` | `launched: false`, `session.endpoint: null` | never launched; no session exists |
62
+ | **sent** | `{launched: true, backend, provider, launchSent: t}` (no endpoint) | `launched: true` (not compared) | a first launch was sent; its outcome is not recorded |
63
+ | **running** | `{launched: true, …, endpoint: E, stoppedAt: null}` | `launched: true`, `session.endpoint: E`, `startId` | OATS started a session at `E` and has not stopped it |
64
+ | **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) |
65
+ | **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 |
66
+
67
+ Two things are not states of the records:
68
+
69
+ - **lost**: the records say *running* and the provider says the session is
70
+ gone. Only an inspect tells; nothing is written. A lost session is resumed
71
+ through `input`, under the home's cap.
72
+ - **retiring**: any state, with the claim held by a retire. It ends with the
73
+ home removed.
74
+
75
+ *sent* and *resent* are the **unsettled** states: a session may run that no
76
+ record names. A launch in progress and a launch whose command died look the
77
+ same to a read; the claim tells them apart for a verb (a live holder is busy;
78
+ a dead one is taken over).
79
+
80
+ **The older kernel.** A kernel from before session providers refuses every
81
+ verb on a home whose receipt says `launched: true` without a tmux endpoint,
82
+ a retire included, and would retire a `launched: false` home as never
83
+ launched. That is why *sent* says `launched: true` in the receipt and in the
84
+ record, though no session is known to exist.
85
+
86
+ ## Settling
87
+
88
+ An unsettled home is settled by one procedure, used by every verb that acts
89
+ on it (stop, start, restart, retire), under that verb's claim:
90
+
91
+ 1. Ask the provider: `stop {home, endpoint: null, launchSent: t}`: stop
92
+ whatever session rooted at this home was created at or after `t`.
93
+ 2. Not confirmed: `E_SESSION_STOP_FAILED`; the state is unchanged, and the
94
+ next verb asks again. (A retire goes on all the same when no process works
95
+ in the home, with a warning that names the provider's own tooling: it
96
+ never strands a home on a provider that does not answer.)
97
+ 3. Confirmed: no session of that launch runs. The record is rewritten to
98
+ agree with what the receipt will say, then the receipt:
99
+ - from *sent* → **planned** (record `launched: false`, `endpoint: null`);
100
+ - from *resent* → **stopped** (record `launched: true`, `endpoint: E`;
101
+ receipt `stoppedAt` set if it was null, `launchSent` removed; the stop
102
+ receipt as an operator's, unless it already says the host's).
103
+
104
+ *resent* settles to *stopped*, never to *running*. Step 1 does not reach the
105
+ session at `E`: it is older than the launch (a start of a lost home stops it
106
+ only after its mark, and may have died before). So **every verb that settles
107
+ a resent home asks `stop {endpoint: E}` first**, and settles only once that
108
+ is confirmed: then neither the old session nor the new launch's runs. Not
109
+ confirmed, the home is not settled, whichever verb asked (a retire, which
110
+ removes the home, asks for both stops all the same and records nothing).
111
+
112
+ ## A launch (spawn's, start's, restart's)
113
+
114
+ Always the same steps, under the home's claim (`start`; a spawn takes it
115
+ before its home can be acted on):
116
+
117
+ | # | Step | Record written | State after |
118
+ |---|---|---|---|
119
+ | 1 | What can refuse, in this order: a module of the home the kernel holds no copy of (it runs its own copy of each, and reads their manifests there); the provider's `check` with the planned launch (the harness, yolo, the sandbox allowances, the home's trees and the launch configuration's own arguments), **before any hook runs**; then the plan and the launch hooks. A spawn or a start its backend refuses runs no hook. (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 |
120
+ | 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 |
121
+ | 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 |
122
+ | 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 |
123
+ | 5 | The provider's `launch` | none | sent or resent |
124
+ | 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'` |
125
+ | 6b | It refused (nothing was started): **unmark**: record, then receipt | record, then receipt | as before step 4 |
126
+ | 6c | Its answer was lost: settle | see Settling | planned or stopped; or unchanged when the stop is not confirmed |
127
+
128
+ A launch killed at any point after step 4 and before the last write of 6a
129
+ leaves an unsettled home: the next verb settles it. There is no point at
130
+ which the receipt names a session the record contradicts, or at which a
131
+ session runs that the receipt does not account for with either an endpoint
132
+ or `launchSent`.
133
+
134
+ A spawn writes its home's receipt, as planned, BEFORE it publishes the
135
+ record, and again after it; so a spawn that ends between the two leaves a
136
+ planned home, never a record without a receipt, and a spawn that reuses the
137
+ name of a retired home (whose receipt a retire keeps, by its path) is never
138
+ paired with that one. A spawn that fails after step 4 undoes itself: 6b or
139
+ 6c (its fence first: the launch's mark, written again if it was gone
140
+ 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
141
+ hook's cleanup is owed) is left planned, record and receipt alike, with its
142
+ rollback marker. When the stop of 6c is not confirmed the home is retained,
143
+ unsettled, with its rollback marker. A retire of a retained provider home
144
+ reads the launch from its receipt and record, never from the marker.
145
+
146
+ ## The verbs, by state
147
+
148
+ `—` means the provider is not called.
149
+
150
+ | Verb (claim) | planned | sent | running | stopped | resent |
151
+ |---|---|---|---|---|---|
152
+ | **inspect**, **status** (none) | not launched; — | unknown (`E_SESSION_UNAVAILABLE`; row `unreachable`); — | the provider's `inspect`; unknown when it fails; gone reads *lost* | stopped; — | unknown; — |
153
+ | **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`; — |
154
+ | **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 |
155
+ | **start** (`start`) | launch | settle, launch | `inspect`: there → `E_SESSION_RUNNING` or `E_SESSION_UNKNOWN`; gone → launch | launch | `stop {E}`, settle, launch |
156
+ | **restart** (`start`) | launch | settle, launch | `inspect` (unknown refuses): there → the stop rule, launch; gone → launch | launch | `stop {E}`, settle, launch |
157
+ | **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` |
158
+ | **retire** (`retire`) | remove | settle, scan, remove | the stop rule, scan, remove | `stop {E}` again, scan, remove | the stop rule, settle, scan, remove |
159
+
160
+ **The stop rule: fence, drain, stop.** Every stop the kernel asks of a
161
+ provider, whatever the verb, is made by one function, in this order:
162
+
163
+ 1. The **fence**: the record from which no new input is admitted. For a stop
164
+ of a *running* home (stop, restart, retire, the host's shutdown): an
165
+ earlier stop's receipt is removed (one a resume that died left names this
166
+ same start, and would make this stop the host's), then receipt
167
+ `stoppedAt: t`, then the stop receipt. For a launch: its mark. A home
168
+ that is stopped or unsettled already has its fence. A fence that cannot
169
+ be written refuses the verb before the provider is asked, a retire too:
170
+ without it an input is still admitted.
171
+ 2. The **drain** of the provider calls recorded for the home (see "A
172
+ provider's command outlives the kernel that ran it"): an input that is
173
+ being sent is waited for, at most an input's timeout and a margin (about
174
+ 25 s), and ended if it outlasts that or if its kernel is gone.
175
+ 3. The provider's `stop {endpoint: E}`.
176
+
177
+ A stop the provider confirms is therefore final: nothing admitted before the
178
+ fence is still on its way. Not confirmed is `E_SESSION_STOP_FAILED` (a
179
+ retire goes on when no process works in the home, with a warning), and the
180
+ home is *stopped* all the same: from the fence on, input is refused whatever
181
+ the provider does. The cost is the wait of step 2, while an input is in
182
+ flight.
183
+
184
+ **Scan** (a retire): no process may work in the home after the provider's
185
+ stop, confirmed or not.
186
+
187
+ **A resume's notice that fails.** Refused by the provider (a prompt is open,
188
+ it was queued): nothing was sent; a lost session's count is given back, and a
189
+ home stopped with the host stays so, still to resume. Failed otherwise: the
190
+ provider may have restarted the session on it; a lost session's count stays,
191
+ and for a home stopped with the host, which stays stopped, the provider is
192
+ asked `stop {E}` again.
193
+
194
+ **Input to a running home**: `inspect`; gone is a lost session, whose input
195
+ is a resume (counted before the provider is called, refused at the cap);
196
+ then the record is read again, `input` is sent, and the record is read once
197
+ more (the crossing check, below).
198
+
199
+ ## Crossings
200
+
201
+ **A verb arrives while another holds the claim.** Stop, start, restart,
202
+ resume and retire take the claim; a second one is refused as busy
203
+ (`E_LIFECYCLE_BUSY`, `E_SESSION_START_BUSY`, …) before any effect. A spawn
204
+ of a provider home, launched or not, holds the claim from before its home is *planned* on disk until its last
205
+ write of the home's record (after its launch is recorded) or until its
206
+ launch is undone, so the home is never acted on while it launches, and no
207
+ verb's record is overwritten by the spawn's.
208
+ Reads (inspect, status, the plans) take no claim: they answer the state the
209
+ records spell at that instant, which during a launch is *sent* or *resent*,
210
+ that is, unknown.
211
+
212
+ **The holder died.** A claim names its holder by process id and that
213
+ process's start time. A holder is gone when no process has that id, or the
214
+ one that has it started at another time (the id was reused), or it is a
215
+ zombie; a holder whose liveness cannot be read is not gone, and the verb is
216
+ refused as busy. The next verb takes over a gone holder's claim. The records
217
+ are in one of the states above whatever the point of death, by the write
218
+ orders of "A launch" and of the stop rule:
219
+
220
+ | Died | State left | The next verb |
221
+ |---|---|---|
222
+ | before the mark (step 4) | as before the verb | acts on it |
223
+ | between the mark's two writes | sent, record `launched: false` (not compared) | settles |
224
+ | 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` |
225
+ | 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 |
226
+ | during a settle, after the provider confirmed | unsettled still, or settled | settles again (the provider's stop is idempotent), or acts |
227
+ | during a launch the provider refused, between the record and the receipt of its unmarking | sent | settles (there is nothing to stop) |
228
+ | 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 |
229
+ | during a spawn's rollback, between its record and its receipt | unsettled: the launch still marked, the record already planned (not compared) | settles |
230
+ | during a spawn, before its record (while the provider's `check` is asked, or its hooks run) | not a home of the table yet: a receipt, where there is one, says planned, and the record is the one its files were composed with. A read answers that it is being spawned (`E_SESSION_UNAVAILABLE`), never that its records disagree | as for any spawn that ended before its record: the kernel has no verb for it yet (not this change's) |
231
+ | during a spawn, between the planned record and its last receipt | planned (the receipt was written before the record) | acts on it |
232
+ | 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}` |
233
+ | 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 |
234
+
235
+ **An input in flight across a state change.** An input holds no claim and a
236
+ provider restarts a session on it, so the kernel checks after the send, with
237
+ one read of the home, whatever the provider answered (a refusal included):
238
+
239
+ | What the read says | What happened | What the kernel does |
240
+ |---|---|---|
241
+ | running, the same `startId` and endpoint | nothing | answers the provider's answer |
242
+ | 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 |
243
+ | unsettled | a start is launching | `stop {E}` again; `E_SESSION_NOT_RUNNING`, not delivered |
244
+ | running, another `startId`, another endpoint | a restart landed | `stop {E}` again (the old one); `E_SESSION_NOT_RUNNING` |
245
+ | 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 |
246
+
247
+ Since every stop drains (the stop rule), a stop's and a restart's own stop
248
+ wait for the input, which then reads the home *stopped*: the two rows
249
+ "running, another `startId`" are reached only by an input that outlasted the
250
+ drain's wait: its provider call is ended there, and its kernel, still
251
+ running, reads the home after the restart recorded its launch.
252
+
253
+ The same read before the send refuses without sending. A start of a lost
254
+ home stops the session at `E` after its mark (step 4), which covers the
255
+ input that finished before the mark: its provider call had ended by then, so
256
+ the session it restarted at `E` is stopped before the new one is launched,
257
+ and an input that reads the home after the mark stops it itself (the row
258
+ "unsettled").
259
+
260
+ A provider that hands a launch an endpoint it used before for the home
261
+ breaks the rule below. In the rows "stopped" and "unsettled" the `stop {E}`
262
+ then addresses whatever session holds that locator by then, which can be the
263
+ new one: the home is recorded running, its session is gone, it reads lost,
264
+ and the next input resumes it.
265
+
266
+ **The drain, and an input in flight.** An input holds no claim, so one can
267
+ be on its way when a stop, a start or a retire writes its fence. After a
268
+ stop or a restart the input itself could still ask the provider to stop
269
+ again (the table above); after a retire it could not: the home, and the
270
+ provider's commands with it, are gone; and an input whose kernel is killed
271
+ asks for nothing. So an input records that it is in flight, outside the
272
+ home, before its read of the home and until its answer, and **every stop
273
+ drains before it asks the provider**: it waits for the inputs in flight to
274
+ end, at most an input's timeout and a margin; one whose kernel is gone, or
275
+ dies meanwhile, is ended at once (below); one still in flight at the bound
276
+ is ended too (a retire then says so, naming the input's process).
277
+
278
+ **A provider's command outlives the kernel that ran it.** The kernel runs
279
+ every command of a provider in a process group of its own. A kernel that is
280
+ killed while it waits for one leaves that command running: a launch that
281
+ creates its session later, an input that restarts one, a stop that stops a
282
+ session resumed since. So a launch, an input and EVERY stop the kernel sends
283
+ (one function sends them all: a verb's, a spawn's rollback, an input's own
284
+ after a crossing) are recorded while they run (the table at the top: the kernel that made the
285
+ call, and the group its command runs in, written by the group's leader
286
+ before the provider runs), and the record is removed when the call returns.
287
+
288
+ A record whose kernel is gone is a call that may still act. The kernel
289
+ **ends** it: the group is killed (SIGKILL) and seen empty. A call whose
290
+ group had not recorded itself yet is made void: the kernel creates the
291
+ group's file itself, removes the call's record, then that file (both the
292
+ leader and the kernel publish that file whole, by an exclusive link from a
293
+ file of their own, so neither ever finds it half written); a leader
294
+ that comes late finds the file, or finds its call's record gone, and runs
295
+ nothing. A group that cannot be ended (its leader is gone and members are
296
+ left, or they survive) refuses the verb: `E_SESSION_STOP_FAILED` for a stop,
297
+ and an unsettled home stays unsettled.
298
+
299
+ Such calls are ended **before a provider's stop is relied on** (the drain),
300
+ and **before a launch, an input or a resume's notice is sent** (a stop left
301
+ behind would run late and stop what they start).
302
+
303
+ One window stays: a request the provider's own server had accepted before
304
+ the group was killed can complete moments later. The provider's `stop`,
305
+ which the kernel sends after the group is gone, is what covers it.
306
+
307
+ **Resume count.** Taken under its own lock, before the provider's `input`,
308
+ and given back only when the provider itself refused the input.
309
+
310
+ ## What a provider must do for this to hold
311
+
312
+ - `stop` is idempotent, and with `endpoint: null` stops whatever session
313
+ rooted at the home was created at or after `launchSent`.
314
+ - `launch` either answers an endpoint for a session it started, or refuses
315
+ having started nothing. **The endpoint it answers differs from every
316
+ endpoint it answered before for that home**: an endpoint names one session,
317
+ never a place that a later session takes over.
318
+ - `input` answers `submitted: true` only when it dispatched the input.
319
+ - A command runs its own helpers inside the process group the kernel runs
320
+ it in, and never detaches them: ending the group ends everything the
321
+ command would still do on this host. Its `stop` looks at what is there
322
+ when it is asked, after that group is gone.
@@ -26,13 +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.
33
- - [Sandboxes](2026-11-19-sandboxes.md) (contracts decided, not built):
34
- boundaries declared in the workspace's `sandboxes:`, started by `oats sync` on
35
- the machines that list them.
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).
36
40
 
37
41
  The Desktop's design brief for designers is in
38
42
  [packages/desktop/docs](../../packages/desktop/docs/design-brief.md).