@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.
Files changed (74) hide show
  1. package/bin/oats.mjs +141 -364
  2. package/docs/configuration.md +12 -0
  3. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  4. package/docs/design/2026-10-29-warm-reader.md +261 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +258 -13
  7. package/docs/execution-targets.md +36 -5
  8. package/docs/implementation.md +34 -9
  9. package/docs/integrations.md +2 -2
  10. package/docs/knowledge.md +18 -8
  11. package/docs/named-test-runs.md +4 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-notes/v0.69.5.md +146 -0
  15. package/docs/release-notes/v0.69.6.md +165 -0
  16. package/docs/schedules.md +8 -1
  17. package/docs/tui.md +23 -5
  18. package/docs/upgrading.md +20 -5
  19. package/docs/workspaces.md +2 -2
  20. package/lib/agents-root.mjs +51 -0
  21. package/lib/argv.mjs +41 -0
  22. package/lib/automation-api.mjs +7 -0
  23. package/lib/automation-scope.mjs +37 -0
  24. package/lib/automations.mjs +63 -12
  25. package/lib/captured-context.mjs +12 -0
  26. package/lib/compile-cache.mjs +36 -0
  27. package/lib/core.mjs +39 -1348
  28. package/lib/deployment-path.mjs +127 -0
  29. package/lib/deployments.mjs +2 -2
  30. package/lib/drift.mjs +95 -0
  31. package/lib/hot-reads.mjs +137 -0
  32. package/lib/install-stamp.mjs +61 -0
  33. package/lib/instance-address.mjs +21 -0
  34. package/lib/instance-events.mjs +8 -6
  35. package/lib/instance-lifecycle.mjs +4 -16
  36. package/lib/instance-listing.mjs +738 -0
  37. package/lib/instance-resolution.mjs +5 -166
  38. package/lib/kernel-features.mjs +10 -0
  39. package/lib/local-edit.mjs +1 -1
  40. package/lib/local-inputs.mjs +3 -0
  41. package/lib/materialize.mjs +2 -87
  42. package/lib/member-clone.mjs +192 -0
  43. package/lib/package-catalog.mjs +93 -0
  44. package/lib/packages.mjs +4 -24
  45. package/lib/read-call.mjs +143 -0
  46. package/lib/reader.mjs +203 -0
  47. package/lib/remote.mjs +47 -6
  48. package/lib/reserved-launch-env.mjs +20 -0
  49. package/lib/resolved-deployment.mjs +13 -5
  50. package/lib/roster-read.mjs +199 -0
  51. package/lib/schedule.mjs +5 -29
  52. package/lib/semver.mjs +12 -0
  53. package/lib/servers.mjs +10 -12
  54. package/lib/session-end.mjs +3 -2
  55. package/lib/session-input.mjs +35 -11
  56. package/lib/session-inspect.mjs +219 -0
  57. package/lib/soul-listing.mjs +216 -0
  58. package/lib/status-words.mjs +30 -0
  59. package/lib/version.mjs +9 -0
  60. package/lib/workspace-read.mjs +160 -0
  61. package/lib/write-file-atomic.mjs +28 -0
  62. package/package-catalog.json +4 -4
  63. package/package.json +1 -1
  64. package/packages/client/cli-locator.mjs +1 -0
  65. package/packages/client/cli-probe-contract.mjs +4 -2
  66. package/packages/client/deployment-observer.mjs +8 -3
  67. package/packages/client/deployment-panel.mjs +17 -1
  68. package/packages/client/deployment-read-cli.mjs +48 -27
  69. package/packages/client/own-codes.mjs +3 -0
  70. package/packages/client/warm-reader.mjs +241 -0
  71. package/packages/tui/lib/client.mjs +2 -1
  72. package/packages/tui/lib/read.mjs +59 -11
  73. package/packages/tui/lib/store.mjs +7 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -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.
@@ -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).