@awebai/oats 0.69.4 → 0.69.6
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 +141 -364
- package/docs/configuration.md +12 -0
- package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
- package/docs/design/2026-10-29-warm-reader.md +261 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +258 -13
- package/docs/execution-targets.md +36 -5
- package/docs/implementation.md +34 -9
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +18 -8
- package/docs/named-test-runs.md +4 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.69.5.md +146 -0
- package/docs/release-notes/v0.69.6.md +165 -0
- package/docs/schedules.md +8 -1
- package/docs/tui.md +23 -5
- package/docs/upgrading.md +20 -5
- package/docs/workspaces.md +2 -2
- package/lib/agents-root.mjs +51 -0
- package/lib/argv.mjs +41 -0
- package/lib/automation-api.mjs +7 -0
- package/lib/automation-scope.mjs +37 -0
- package/lib/automations.mjs +63 -12
- package/lib/captured-context.mjs +12 -0
- package/lib/compile-cache.mjs +36 -0
- package/lib/core.mjs +39 -1348
- package/lib/deployment-path.mjs +127 -0
- package/lib/deployments.mjs +2 -2
- package/lib/drift.mjs +95 -0
- package/lib/hot-reads.mjs +137 -0
- package/lib/install-stamp.mjs +61 -0
- package/lib/instance-address.mjs +21 -0
- package/lib/instance-events.mjs +8 -6
- package/lib/instance-lifecycle.mjs +4 -16
- package/lib/instance-listing.mjs +738 -0
- package/lib/instance-resolution.mjs +5 -166
- package/lib/kernel-features.mjs +10 -0
- package/lib/local-edit.mjs +1 -1
- package/lib/local-inputs.mjs +3 -0
- package/lib/materialize.mjs +2 -87
- package/lib/member-clone.mjs +192 -0
- package/lib/package-catalog.mjs +93 -0
- package/lib/packages.mjs +4 -24
- package/lib/read-call.mjs +143 -0
- package/lib/reader.mjs +203 -0
- package/lib/remote.mjs +47 -6
- package/lib/reserved-launch-env.mjs +20 -0
- package/lib/resolved-deployment.mjs +13 -5
- package/lib/roster-read.mjs +199 -0
- package/lib/schedule.mjs +5 -29
- package/lib/semver.mjs +12 -0
- package/lib/servers.mjs +10 -12
- package/lib/session-end.mjs +3 -2
- package/lib/session-input.mjs +35 -11
- package/lib/session-inspect.mjs +219 -0
- package/lib/soul-listing.mjs +216 -0
- package/lib/status-words.mjs +30 -0
- package/lib/version.mjs +9 -0
- package/lib/workspace-read.mjs +160 -0
- package/lib/write-file-atomic.mjs +28 -0
- package/package-catalog.json +4 -4
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +1 -0
- package/packages/client/cli-probe-contract.mjs +4 -2
- package/packages/client/deployment-observer.mjs +8 -3
- package/packages/client/deployment-panel.mjs +17 -1
- package/packages/client/deployment-read-cli.mjs +48 -27
- package/packages/client/own-codes.mjs +3 -0
- package/packages/client/warm-reader.mjs +241 -0
- package/packages/tui/lib/client.mjs +2 -1
- package/packages/tui/lib/read.mjs +59 -11
- package/packages/tui/lib/store.mjs +7 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/configuration.md
CHANGED
|
@@ -655,6 +655,18 @@ home has its own copy under `<home>/.oats/modules/<capability>/`
|
|
|
655
655
|
([souls-and-instances.md](souls-and-instances.md)). The store is a cache; it
|
|
656
656
|
is safe to delete.
|
|
657
657
|
|
|
658
|
+
## The compile cache
|
|
659
|
+
|
|
660
|
+
Every `oats` command keeps Node's compile cache in `~/.oats/compile-cache`
|
|
661
|
+
(`$OATS_HOME_DIR/compile-cache` when `OATS_HOME_DIR` is set), so a command
|
|
662
|
+
does not recompile the kernel each time it starts. The CLI creates the
|
|
663
|
+
directory mode 0700. It is a cache: delete it at any time; it holds one
|
|
664
|
+
subdirectory per Node version, so it grows a little with each Node upgrade.
|
|
665
|
+
Node's own variables override it: `NODE_COMPILE_CACHE=<dir>` moves it there,
|
|
666
|
+
and `NODE_DISABLE_COMPILE_CACHE=1` turns it off. A cache that cannot be
|
|
667
|
+
written means no cache, never a different answer. Hooks and other processes the
|
|
668
|
+
CLI starts do not inherit it.
|
|
669
|
+
|
|
658
670
|
## What is not in it
|
|
659
671
|
|
|
660
672
|
- **Which capabilities a soul gets:** the soul's `capabilities:` plus the
|
|
@@ -125,6 +125,7 @@ Otherwise it is listed with the reason `assigned-elsewhere`, `owner-mismatch` (n
|
|
|
125
125
|
3. **Tasks:** if the provenance names a tasks provider and refs, and its own tasks capability matches, it reads those tickets. Otherwise the verdict records `tasks: "unavailable"`. This is never a blocker.
|
|
126
126
|
4. **Verdict**, recorded as a structured `okf-review` PR comment: `merge`; `amend+merge` (it pushes fixes, supersession edits in other concepts of the same base, index and log to the PR branch); `request-changes` (it messages the harvester and waits, bounded); `close` (with the reason); `needs-human`. It checks the doctrine's two-part test, one canonical home, explicit supersession and provenance.
|
|
127
127
|
5. **Human-accepted decisions are never superseded silently.** A PR that would supersede a concept with human acceptance evidence is not merged: the maintainer labels it `okf-needs-human` and asks a human. That label is a hard stop that only a human removes.
|
|
128
|
+
*Superseded by oats.okf 5.7.0 ([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)): the maintainer never parks a PR; it merges such a supersession only with the human's acceptance cited (checked when the record is on GitHub, otherwise recorded as source-reported) and closes it otherwise.*
|
|
128
129
|
6. It merges with the host's `gh` (squash, pinned to the reviewed head), notifies the harvester (`merged` or `closed`) and retires.
|
|
129
130
|
|
|
130
131
|
**Messaging:** the harvester and the maintainer talk through the soul's messaging capability, in the deployment's default team like every instance. There is no dedicated team to declare; a deployment that wants them in another team opts them in locally, as for any soul (see [the team model](2026-09-27-team-model-v2.md)).
|
|
@@ -160,5 +161,6 @@ The oats.okf inject teaches a work mode over both kinds of knowledge:
|
|
|
160
161
|
3. **Workspace automations are placed by declaration:** `runsOn` names the one host, `owner` the account it acts as, and a host runs one only when both match.
|
|
161
162
|
4. **The harvester is a package soul** (it needs messaging and a lifetime past its PR); capability agents are removed.
|
|
162
163
|
5. **The maintainer merges autonomously** when the doctrine passes, except where it would supersede a human-accepted decision (`okf-needs-human`).
|
|
164
|
+
*Superseded by oats.okf 5.7.0 ([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)): no exception remains, and the maintainer settles every PR itself: a supersession of a human-accepted decision merges when it cites the human's acceptance and is closed otherwise.*
|
|
163
165
|
6. **The harvester and the maintainer hold no knowledge slot** (no recursive harvest).
|
|
164
166
|
7. **Harvest is opt-in per host and opt-out per soul**, and the soul's opt-out is absolute.
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# The warm reader: an app-owned child that answers the poll's reads (#1630)
|
|
2
|
+
|
|
3
|
+
Status: decided 2026-10-29 (option C of #1630, with the conditions agreed on
|
|
4
|
+
that issue). The contract is
|
|
5
|
+
[The warm reader](../desktop-cli-api.md#the-warm-reader) in the Desktop CLI
|
|
6
|
+
API; when this record and that page disagree, the page wins.
|
|
7
|
+
|
|
8
|
+
## Context
|
|
9
|
+
|
|
10
|
+
The Desktop and the TUI poll each served local deployment every few seconds.
|
|
11
|
+
Each tick runs two CLI processes, `oats status --dir <D> --max-age 60 --json`
|
|
12
|
+
and `oats workspace status --dir <D> --max-age 60 --json`, plus a liveness
|
|
13
|
+
collector child: every read is a new process that starts Node and loads the
|
|
14
|
+
kernel's code again. The clients must not import kernel code (the
|
|
15
|
+
minimal process boundary), and every answer they read is the CLI's public
|
|
16
|
+
JSON, validated once.
|
|
17
|
+
|
|
18
|
+
The kernel answers those two reads from a process the app starts once and
|
|
19
|
+
keeps: the same install, the same code, loaded once, answering many times.
|
|
20
|
+
|
|
21
|
+
## Decisions
|
|
22
|
+
|
|
23
|
+
### D1. A kernel command, a process, the public JSON
|
|
24
|
+
|
|
25
|
+
`oats reader --stdio` is a kernel command. It keeps the minimal process
|
|
26
|
+
boundary: a client talks to a process in the CLI's own JSON and never imports
|
|
27
|
+
kernel code.
|
|
28
|
+
|
|
29
|
+
Rejected:
|
|
30
|
+
- A socket or a service: the reader is owned by the app that starts it, over
|
|
31
|
+
stdin and stdout, and dies with it; nothing to install, register or accept.
|
|
32
|
+
- An importable kernel API for clients: it breaks the process boundary.
|
|
33
|
+
|
|
34
|
+
### D2. One implementation: both reads lifted into `lib/`
|
|
35
|
+
|
|
36
|
+
The document assembly of `status --json` and `workspace status --json` lives
|
|
37
|
+
in `lib/` leaves (`lib/roster-read.mjs`, `lib/workspace-read.mjs`), in two
|
|
38
|
+
layers: a data function the CLI's text mode renders from, and an answer
|
|
39
|
+
function, `{exit, answer, stderr}`, over it. The answer takes an explicit
|
|
40
|
+
context (the absolute `dir`, `maxAge`, the caller's read session, the budget,
|
|
41
|
+
the cache, the deployments observer) where there were module-level globals.
|
|
42
|
+
The read part of the dispatch is lifted beside them (`lib/read-call.mjs`),
|
|
43
|
+
because it is part of the answer: the `--max-age` parse and validation, the
|
|
44
|
+
refusal of an inherited `OATS_RESOLUTION` or `OATS_DEPLOYMENT`, and `--team`.
|
|
45
|
+
`KERNEL_FEATURES` is a `lib/` leaf imported by `version`, `status` and the
|
|
46
|
+
reader. The new modules are leaves (never `core.mjs`, `bin`, or a module they
|
|
47
|
+
were split from), every import specifier is one literal, and each piece of
|
|
48
|
+
mutable state has one owning module. Every CLI answer is byte-for-byte
|
|
49
|
+
unchanged.
|
|
50
|
+
|
|
51
|
+
Rejected:
|
|
52
|
+
- Re-entering `bin`'s dispatch per request: module-level argv globals and
|
|
53
|
+
`process.exit` everywhere.
|
|
54
|
+
- Re-evaluating `bin` per request by URL: it leaks module records.
|
|
55
|
+
- A second, reader-only assembly: a duplicate of the reads, the option #1630
|
|
56
|
+
rejected.
|
|
57
|
+
|
|
58
|
+
### D3. Warm code, not warm data: per-request state is enumerated and reset
|
|
59
|
+
|
|
60
|
+
In a one-shot CLI, process exit is the read path's cache invalidation. The
|
|
61
|
+
reader keeps only loaded code and install-derived constants; every request
|
|
62
|
+
reads the deployment afresh, and `--max-age` reuse is the CLI's own on-disk
|
|
63
|
+
observation reuse, nothing more.
|
|
64
|
+
|
|
65
|
+
- Every piece of module-level state the reads can reach has a row in
|
|
66
|
+
`READ_STATE` (`lib/read-call.mjs`), with its disposition: reset or scoped
|
|
67
|
+
per call (the local inputs, the resolved-deployment observer, settled at the
|
|
68
|
+
end of each request, the deprecation sources, the remote layer's ssh
|
|
69
|
+
command, git version and protocol pin caches), or safe, with the reason (an
|
|
70
|
+
in-process mutex that cleans itself, WeakMaps keyed on per-request objects,
|
|
71
|
+
install data the stamp of D7 covers, the boot id, pure constant caches). A
|
|
72
|
+
test scans the reads' real import closure, `bin`'s lazy imports included,
|
|
73
|
+
and fails on a binding with no row.
|
|
74
|
+
- `lib/session-viewer.mjs` `probed` is safe rather than reset: only an
|
|
75
|
+
attach reads it, and `readSessionViewer` asks `tmux -V` on every call, so
|
|
76
|
+
"afresh at every run" holds without a reset.
|
|
77
|
+
- The registry of live git process groups is not state to reset: it is empty
|
|
78
|
+
when a request ends, after its session closed.
|
|
79
|
+
- The read session is created when a request starts (its budget deadline is
|
|
80
|
+
fixed then) and closed when it ends. The lifted code takes its session from
|
|
81
|
+
the caller and registers no process listener; the CLI keeps its own
|
|
82
|
+
command session.
|
|
83
|
+
- The lifted code reads no working directory. The programs the reads run by
|
|
84
|
+
name (`tmux`, `git`) are found on `PATH`, and a relative or empty `PATH`
|
|
85
|
+
entry resolves against the process's working directory. The reader
|
|
86
|
+
therefore changes its working directory to the request's `--dir` before the
|
|
87
|
+
read and back to its install root when the request ends, answered or
|
|
88
|
+
failed: it never keeps a deployment directory that may be removed or
|
|
89
|
+
unmounted. A `--dir` it cannot change to is refused
|
|
90
|
+
(`E_READER_UNSUPPORTED`), so the CLI fallback gives the CLI's own failure;
|
|
91
|
+
the reader never makes up an answer for it. The equivalence baseline is the
|
|
92
|
+
CLI run with the same environment and cwd = `--dir`. This depends on
|
|
93
|
+
answering one request at a time: a reader that answers two at once must
|
|
94
|
+
first give each child it runs its own working directory.
|
|
95
|
+
- Tests answer many requests in one process (alternating deployments,
|
|
96
|
+
`--max-age` absent, 0 and 60, error paths) and compare each answer with a
|
|
97
|
+
fresh CLI run's; a differential test changes the deployment between
|
|
98
|
+
requests (a spawn and a retire by another process, an edited
|
|
99
|
+
`oats-local.yaml` and lock, a killed session, a program added to `PATH`).
|
|
100
|
+
|
|
101
|
+
Rejected: keeping parsed deployment state between requests, with
|
|
102
|
+
invalidation. A missed invalidation gives a plausible wrong answer, not a
|
|
103
|
+
crash.
|
|
104
|
+
|
|
105
|
+
### D4. Every module is loaded once, before the hello
|
|
106
|
+
|
|
107
|
+
The reads' full closure, the modules they import lazily included, is loaded
|
|
108
|
+
before the reader sends its hello, so a hello means ready and no request waits
|
|
109
|
+
on a module load. The reader classifies a request with the kernel's hot-read
|
|
110
|
+
forms but does not load through the hot-read table, so a `HotReadUnlisted`
|
|
111
|
+
tripwire can never reach a reader answer.
|
|
112
|
+
|
|
113
|
+
`oats reader --stdio` is itself a hot-read form (`lib/hot-reads.mjs`): `bin`
|
|
114
|
+
loads only its dispatch's own leaves for it, never `core.mjs` or the other
|
|
115
|
+
modules of the full command set, and `lib/reader.mjs`'s own imports, with
|
|
116
|
+
`PRELOAD`, load the reads. Every module the reads use, and nothing the CLI's
|
|
117
|
+
other commands need, is loaded before the hello (measured on a real
|
|
118
|
+
deployment: the hello in about 140–180 ms instead of about 300, and about
|
|
119
|
+
20 MiB less resident memory while it answers a poll). `test/cli-hot-reads.test.mjs` pins that no heavy module loads before
|
|
120
|
+
it.
|
|
121
|
+
|
|
122
|
+
Rejected:
|
|
123
|
+
- Loading on first use, which puts a module load inside the first request's
|
|
124
|
+
deadline.
|
|
125
|
+
- Loading the CLI's full module set first, as every command that is no hot
|
|
126
|
+
read does: it adds `core.mjs` and the rest, which no read uses, to the
|
|
127
|
+
reader's start and its memory for its whole life.
|
|
128
|
+
|
|
129
|
+
### D5. Two reads, one at a time
|
|
130
|
+
|
|
131
|
+
The reader answers the hot reads `status` and `workspace status`, in arrival
|
|
132
|
+
order, one at a time: the state of D3 and the working directory are
|
|
133
|
+
process-wide. The protocol lets answers arrive out of order (matched by `id`)
|
|
134
|
+
and lists the reads in the hello, so a later kernel can add a read or a
|
|
135
|
+
second lane without a contract change; a second lane cannot keep D3's
|
|
136
|
+
per-request change of working directory.
|
|
137
|
+
|
|
138
|
+
Not answered: any remote route (`--server`, `server roster`), which is bound
|
|
139
|
+
to ssh and would block the queue; `session inspect` and `instance events`,
|
|
140
|
+
which are not on the poll.
|
|
141
|
+
|
|
142
|
+
### D6. The TUI uses the same child reader, through `packages/client`
|
|
143
|
+
|
|
144
|
+
The TUI could call the reads directly; it uses the child instead.
|
|
145
|
+
`packages/tui` may not import `lib/` (the client boundary test), the install
|
|
146
|
+
rule of D7 needs a process that can be restarted, and one client module gives
|
|
147
|
+
both apps one fallback path. The cost is one Node start per TUI session.
|
|
148
|
+
|
|
149
|
+
Rejected: in-process warm reads in the TUI.
|
|
150
|
+
|
|
151
|
+
### D7. Install change: the reader notices and exits
|
|
152
|
+
|
|
153
|
+
The reader takes a stamp of its install before any of the kernel's own
|
|
154
|
+
modules load (`lib/install-stamp.mjs`, Node built-ins only, which the CLI's
|
|
155
|
+
entry point imports statically and calls first for `oats reader`): a stamp
|
|
156
|
+
taken once the kernel had loaded would make a change made while it loaded
|
|
157
|
+
the baseline, and the old code would answer with no refusal. The stamp is
|
|
158
|
+
the install root directory's device and inode; device, inode, size and mtime
|
|
159
|
+
of `package.json`, `bin/oats.mjs`, `package-catalog.json`, every file under
|
|
160
|
+
`lib/`, `docs/*.schema.json`, each runtime dependency's `package.json` where
|
|
161
|
+
it resolves at each stamp (a dependency newly installed nearer the install
|
|
162
|
+
shadows the one loaded) and the real path of the Node binary; the mtime of the
|
|
163
|
+
directories under `lib/` and of `docs/` (a file added or removed). It takes
|
|
164
|
+
the stamp again when a request starts and again just before that request's
|
|
165
|
+
answer is written, so an install that changes while a request runs is not
|
|
166
|
+
answered from the old code either. Any difference, or a file gone (an npm
|
|
167
|
+
global update replaces the package directory; a half-written install also
|
|
168
|
+
reads as changed), refuses that request and every queued one with
|
|
169
|
+
`E_READER_STALE`, and the reader exits 0. The stamp is about 130 `stat`
|
|
170
|
+
calls, within a 2 ms budget. What loads before the first stamp (the entry
|
|
171
|
+
point and three small modules of Node built-ins) is a window of a few
|
|
172
|
+
milliseconds that no stamp can close.
|
|
173
|
+
|
|
174
|
+
Rejected:
|
|
175
|
+
- Hashing the files: a replaced install has new inodes, and an edited file a
|
|
176
|
+
new size or mtime, so `stat` is enough.
|
|
177
|
+
- Timers and file watchers: the stamp is taken on the request path, where a
|
|
178
|
+
change matters, and nowhere else.
|
|
179
|
+
|
|
180
|
+
A `PATH` symlink re-pointed at another install of the same version is
|
|
181
|
+
invisible to any stamp. The client's binding of its reader to the probe
|
|
182
|
+
record it started it for covers that case.
|
|
183
|
+
|
|
184
|
+
### D8. Lifetime belongs to the app
|
|
185
|
+
|
|
186
|
+
The reader installs its exit and signal handlers once, at start. It exits on
|
|
187
|
+
stdin's end or a read error (its app is gone), on `EPIPE` on stdout, on
|
|
188
|
+
`SIGTERM`, `SIGINT` and `SIGHUP` (128 + the signal's number), after
|
|
189
|
+
`E_READER_STALE` (0) and after `E_READER_DEFECT` (1: per-request state may be
|
|
190
|
+
half reset; the stack goes to its stderr). A request in flight when it ends
|
|
191
|
+
is not answered: its read session is closed, killing its `git` children.
|
|
192
|
+
That cleanup runs from an `exit` handler, because the deployments-list lock
|
|
193
|
+
installs signal handlers that call `process.exit` themselves. A reader killed
|
|
194
|
+
with `SIGKILL` leaves its git process groups to their own timeouts, as the
|
|
195
|
+
CLI does. It writes protocol lines and nothing else to stdout: other writes
|
|
196
|
+
go to stderr, and no child on the read path inherits its stdout.
|
|
197
|
+
|
|
198
|
+
`oats reader` is exempt from the dispatch's refusal of an inherited
|
|
199
|
+
`OATS_RESOLUTION` or `OATS_DEPLOYMENT`, so that it starts; each request then
|
|
200
|
+
gets the CLI's own `E_UNSUPPORTED_MODE` answer. The `--flag=value` expansion
|
|
201
|
+
is the CLI's own (`lib/argv.mjs`), so a malformed flag such as `--max-age=`
|
|
202
|
+
gets the CLI's `E_BAD_ARGS`.
|
|
203
|
+
|
|
204
|
+
Rejected: an idle timer, or a lifetime of the reader's own. The app's
|
|
205
|
+
exclusive hold of the reader's stdin is the lifeline: the app's death closes
|
|
206
|
+
it.
|
|
207
|
+
|
|
208
|
+
### D9. The fallback is the CLI read, unchanged
|
|
209
|
+
|
|
210
|
+
Whenever the reader is absent, refuses, times out or dies, the client runs
|
|
211
|
+
that same read through the CLI, exactly as without a reader. This is not an
|
|
212
|
+
adapter for an older kernel: one install, one kernel read code, one
|
|
213
|
+
validation, no shape translation. The reader is an accelerator of identical
|
|
214
|
+
answers, gated on a feature. The reader path adds no validation of its own;
|
|
215
|
+
its stderr is never forwarded, as the CLI path forwards none; refusal and
|
|
216
|
+
fallback are silent in the app's interface, and their diagnostics go to the
|
|
217
|
+
backend's own status (`reader: {state, code}`), not to the renderer.
|
|
218
|
+
|
|
219
|
+
Rejected: wrapping the reader as an adapter with a translation of its own
|
|
220
|
+
(remove, do not wrap): there is one answer shape, and the CLI's validation
|
|
221
|
+
reads it.
|
|
222
|
+
|
|
223
|
+
### D10. The liveness collector leaves the poll, gated on its own feature
|
|
224
|
+
|
|
225
|
+
`status` rows already carry each local instance's liveness, computed by the
|
|
226
|
+
kernel on every call under the pinned pane rule; the kernel is the stronger
|
|
227
|
+
observer (wrapper shells, a missing tmux socket answered as unknown). So the
|
|
228
|
+
tick drops the collector child, which costs more than the reader's whole
|
|
229
|
+
saving target.
|
|
230
|
+
|
|
231
|
+
- A kernel declares feature `status-liveness` when status rows'
|
|
232
|
+
`running`/`runtimeState` are the complete local liveness reading under the
|
|
233
|
+
pinned pane rule, and only once an inconclusive descendant scan answers
|
|
234
|
+
`running: null` with a reason, never `false` (#1641). A client drops the
|
|
235
|
+
collector where the probe lists it, whether the read went through the
|
|
236
|
+
reader or the CLI: the CLI's `status` is equally live. It is not gated on
|
|
237
|
+
`warm-reader`, a different fact.
|
|
238
|
+
- "stopped" versus `running: false`, and the collector's "running"
|
|
239
|
+
`runtimeState`: no consumer distinguishes them. A home with no `tmux`
|
|
240
|
+
record loses the Desktop's terminal open (the collector filled in
|
|
241
|
+
defaults); every spawn records one. No client-side default is added.
|
|
242
|
+
- `agentPane` stays for the Desktop's terminal open, pinned by its test. The
|
|
243
|
+
tests of the kernel-unknown decision are re-pointed at kernel rows, not
|
|
244
|
+
deleted.
|
|
245
|
+
- The collector, its entry point, its tmux status reader, its inputs and
|
|
246
|
+
answers, the TUI's collector and the "terminal-probe" origin for local rows
|
|
247
|
+
are deleted when the Desktop's accepted range's minimum reaches the release
|
|
248
|
+
that declares `status-liveness`.
|
|
249
|
+
|
|
250
|
+
Rejected: keeping the collector beside the reader, which pays a second child
|
|
251
|
+
per tick for facts the roster already carries.
|
|
252
|
+
|
|
253
|
+
## Consequences
|
|
254
|
+
|
|
255
|
+
- One more command whose stdout is not an envelope (`oats reader --stdio`),
|
|
256
|
+
four refusal codes used only on its wire (`E_READER_BAD_REQUEST`,
|
|
257
|
+
`E_READER_UNSUPPORTED`, `E_READER_STALE`, `E_READER_DEFECT`), and the probe
|
|
258
|
+
gains feature `warm-reader` and `readerApi: 1`.
|
|
259
|
+
- A new piece of module-level state on the reads' path needs a row in
|
|
260
|
+
`READ_STATE`, or the closure scan fails.
|
|
261
|
+
- The working directory is per process: a second lane changes D3 first.
|
package/docs/design/README.md
CHANGED
|
@@ -26,6 +26,10 @@ 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 warm reader](2026-10-29-warm-reader.md): `oats reader --stdio`, a
|
|
30
|
+
child the Desktop and the TUI start, answers `oats status` and `oats
|
|
31
|
+
workspace status` with the kernel's own read code kept loaded: warm code,
|
|
32
|
+
not warm data, the same answers as the CLI, and the CLI as the fallback.
|
|
29
33
|
|
|
30
34
|
The Desktop's design brief for designers is in
|
|
31
35
|
[packages/desktop/docs](../../packages/desktop/docs/design-brief.md).
|