@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.
- package/bin/oats.mjs +185 -38
- package/docs/capabilities.md +365 -7
- package/docs/capability-manifest.schema.json +37 -1
- package/docs/configuration.md +27 -7
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +1352 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -0
- package/docs/desktop-cli-api.md +673 -81
- package/docs/desktop.md +241 -65
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +6 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +127 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +96 -22
- package/docs/tui.md +25 -4
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +14 -6
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +40 -3
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1201 -195
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +34 -18
- package/lib/instance-listing.mjs +113 -16
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +13 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +151 -17
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/package-catalog.json +3 -3
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +27 -3
- package/packages/client/deployment-panel.mjs +27 -4
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +9 -3
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- 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.
|
package/docs/design/README.md
CHANGED
|
@@ -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).
|