@awebai/oats 0.69.5 → 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 (48) hide show
  1. package/bin/oats.mjs +78 -320
  2. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  3. package/docs/design/2026-10-29-warm-reader.md +261 -0
  4. package/docs/design/README.md +4 -0
  5. package/docs/desktop-cli-api.md +250 -12
  6. package/docs/execution-targets.md +11 -2
  7. package/docs/implementation.md +26 -8
  8. package/docs/integrations.md +1 -1
  9. package/docs/knowledge.md +14 -7
  10. package/docs/named-test-runs.md +4 -0
  11. package/docs/official-catalog.md +3 -3
  12. package/docs/packages.md +12 -12
  13. package/docs/release-notes/v0.69.6.md +165 -0
  14. package/docs/schedules.md +8 -1
  15. package/docs/tui.md +21 -4
  16. package/docs/upgrading.md +9 -5
  17. package/docs/workspaces.md +2 -2
  18. package/lib/argv.mjs +41 -0
  19. package/lib/automation-scope.mjs +6 -4
  20. package/lib/automations.mjs +61 -11
  21. package/lib/captured-context.mjs +12 -0
  22. package/lib/hot-reads.mjs +21 -15
  23. package/lib/install-stamp.mjs +61 -0
  24. package/lib/instance-events.mjs +8 -6
  25. package/lib/instance-listing.mjs +13 -5
  26. package/lib/kernel-features.mjs +10 -0
  27. package/lib/local-edit.mjs +1 -1
  28. package/lib/local-inputs.mjs +3 -0
  29. package/lib/member-clone.mjs +15 -11
  30. package/lib/read-call.mjs +143 -0
  31. package/lib/reader.mjs +203 -0
  32. package/lib/remote.mjs +47 -6
  33. package/lib/resolved-deployment.mjs +12 -4
  34. package/lib/roster-read.mjs +199 -0
  35. package/lib/session-input.mjs +35 -11
  36. package/lib/workspace-read.mjs +160 -0
  37. package/package-catalog.json +2 -2
  38. package/package.json +1 -1
  39. package/packages/client/cli-locator.mjs +1 -0
  40. package/packages/client/cli-probe-contract.mjs +4 -2
  41. package/packages/client/deployment-observer.mjs +8 -3
  42. package/packages/client/deployment-panel.mjs +17 -1
  43. package/packages/client/deployment-read-cli.mjs +48 -27
  44. package/packages/client/own-codes.mjs +3 -0
  45. package/packages/client/warm-reader.mjs +241 -0
  46. package/packages/tui/lib/client.mjs +2 -1
  47. package/packages/tui/lib/read.mjs +59 -11
  48. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -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).
@@ -73,6 +73,10 @@ see the [official catalog](official-catalog.md) for current pins.
73
73
  at every run and keeps no answer, so read it again after a tmux upgrade.
74
74
  The feature is in every kernel's list that has the field, whatever this
75
75
  host's tmux: gate on the feature, then read the field.
76
+ - `readerApi` (feature `warm-reader`) is the protocol of `oats reader
77
+ --stdio`, which the reader's hello repeats. Start a reader only where the
78
+ probe lists both the feature and `readerApi: 1`
79
+ ([The warm reader](#the-warm-reader)).
76
80
  - In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
77
81
 
78
82
  ### Features
@@ -135,7 +139,7 @@ see the [official catalog](official-catalog.md) for current pins.
135
139
  | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
136
140
  | `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
137
141
  | `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
138
- | `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
142
+ | `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`), and so does a process scan that cannot establish a fallback shell ([#1641](https://github.com/awebai/oats/issues/1641): status reads it `null`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
139
143
  | `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
140
144
  | `session-attach-no-status-line` | `oats session attach … --no-status-line`, local and `--server`: a viewer without a detach key, without its status line (`Shift+PgUp or C-b [ to scroll back`), for a caller that shows the scroll keys itself ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe: a kernel without it ignores the flag and shows the line. A routed attach sends it to any host, with no probe of its own | |
141
145
  | `session-attach-prefix-scroll` | `sessionViewer: {prefixScroll}` on `oats version --json` and `oats status --json`, and `probe.sessionViewer` on each `oats server roster --json` group: whether that host's viewer without a detach key binds `C-b [` (tmux 3.3 and later), read afresh per host at each run. A kernel with the feature has the viewer's `Shift+PgUp` binding; one without it may not, so don't name the viewer's scroll keys for its tabs ([execution-targets.md](execution-targets.md#inspect-input-and-attach)) | |
@@ -156,6 +160,8 @@ see the [official catalog](official-catalog.md) for current pins.
156
160
  | `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
157
161
  | `instance-background` | background instances (awebai/oats#1579): `soul.yaml` `background:`; `oats spawn … --background\|--no-background`, whose preview and result carry `background` and `backgroundFrom`; `oats instance background <instance> on\|off`, local and `--server`; `background: true` on `oats status --json` instance rows, `oats server roster --json` rows, `oats inspect --home` `instance` and `oats souls --json` soul rows, absent otherwise ([Background instances](#background-instances-oats-instance-background)). Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses the flags and the verb, and its rows have no `background`. A routed spawn with either flag needs the host's feature (`E_REMOTE_INCOMPATIBLE`, nothing sent) | `instanceBackgroundApi: 1` (payload only) |
158
162
  | `session-resume` | sessions come back after a shutdown, OATS 0.69 (#1559): `sessionEnd` on `oats status --json` instance rows ([`sessionEnd`](#row-session-end)); `oats session start --resume --home <abs>` and its `resume` answer ([Resume a lost session](#resume-a-lost-session---resume)); the machine sweep `oats session resume [--deployment <dir>] [--plan] --json` ([`oats session resume`](#the-machine-sweep-oats-session-resume)); `E_RESUME_BUSY`, `E_RESUME_NOT_LOST`. Local only: `--server` is `E_BAD_ARGS`. Gate a client's resume-on-open on the probe: a kernel without it has no `session resume` | |
163
+ | `warm-reader` | `oats reader --stdio`, the warm reader: a child process a client starts, which answers `oats status --json` and `oats workspace status --json` on its stdin and stdout, many times, with the CLI's own answers ([The warm reader](#the-warm-reader)). Gate on the probe, never by trying: a kernel without it has no `oats reader` | `readerApi: 1` |
164
+ | `status-liveness` | the local liveness on `oats status --json` instance rows is complete: `running` and `runtimeState` are read live at every call, from the row's recorded tmux server under the pane and shell-descendant rule, with `false` for a shell only on positive evidence and `null` when the reading is inconclusive ([The roster](#the-roster-oats-status---json)). A client needs no liveness probe of its own beside the roster where the probe lists it, whether the read goes through the warm reader or the CLI. Independent of `warm-reader` | |
159
165
 
160
166
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
161
167
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -267,6 +273,7 @@ stdout (progress goes to stderr):
267
273
  | `oats version --json` | the probe |
268
274
  | `oats status --json` | the [roster document](#the-roster-oats-status---json) |
269
275
  | a first `oats retire --json`, and a deferred self-retire | the raw [retire receipt](#retire) |
276
+ | `oats reader --stdio` | the reader's protocol lines ([The warm reader](#the-warm-reader)) |
270
277
 
271
278
  <a id="flags"></a>
272
279
  ### Flag syntax
@@ -326,7 +333,8 @@ message}` and `legacy-local-agents {code, dirs, instances, message}`.
326
333
  Every read asks each remote for its current head (`git ls-remote`). With
327
334
  `--max-age <seconds>` a read verb reuses a head this machine observed at most
328
335
  that many seconds ago instead, so a refresh right after another costs no
329
- network round trip. Gate the flag on the feature: an older kernel may ignore
336
+ network round trip. `oats workspace status` reuses the host's `gh` login the
337
+ same way, for display only ([below](#the-gh-login-display-only)). Gate the flag on the feature: an older kernel may ignore
330
338
  it and answer live, without the block.
331
339
 
332
340
  ```text
@@ -344,10 +352,11 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
344
352
  - **The block:** with the flag (`0` included) the document gains one key,
345
353
  `observation: {observedAt, reused, localRevision}`: in the result of an
346
354
  envelope, at the top level of the roster (after `agents`). `observedAt` is the
347
- OLDEST remote head the answer used, so the answer is at least that fresh
348
- everywhere; `reused` is `true` when any head came from an earlier observation.
349
- A command that read no remote head reports the time it started and
350
- `reused: false`. Without the flag the key is absent and every document is
355
+ OLDEST remote observation the answer used (a head, or a reused `gh` login),
356
+ so the answer is at least that fresh everywhere; `reused` is `true` when any
357
+ head or that login came from an earlier observation.
358
+ A command that used no remote observation (no head, and no reused `gh`
359
+ login) reports the time it started and `reused: false`. Without the flag the key is absent and every document is
351
360
  exactly as before. A refusal (`E_SOUL_UNKNOWN`, any error envelope) never
352
361
  carries the block.
353
362
  - **Spawn preview** (feature `spawn-preview-max-age`, OATS 0.33.0): the
@@ -376,8 +385,9 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
376
385
  not through `localRevision`: the bundled catalog is not an input. Instance
377
386
  homes, member clones and tmux are not inputs either, because the answer
378
387
  itself reports them.
379
- - **What is reused:** only remote heads (the commit a branch or tag named),
380
- never local state. Instances, `oats-local.yaml` and the lock are read afresh
388
+ - **What is reused:** remote heads (the commit a branch or tag named) and,
389
+ in `workspace status`, the `gh` login it places automations with; never
390
+ local state. Instances, `oats-local.yaml` and the lock are read afresh
381
391
  by every command. A member's backlink (`oats-membership.yaml`) is read at
382
392
  the member's observed head, which may be a reused one: a backlink removed
383
393
  less than `<s>` seconds ago can still show the member `confirmed` under
@@ -385,6 +395,27 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
385
395
  afresh. A reused head's
386
396
  `observedAt` (for example `workspace.observedAt` in `workspace status`) is
387
397
  the time it was observed, not now.
398
+ - <a id="the-gh-login-display-only"></a>**The `gh` login, display only:**
399
+ `workspace status` places each workspace trigger and schedule
400
+ with the account this host's `gh` is logged in as (`gh api user`;
401
+ [who runs it](schedules.md#workspace-triggers-and-schedules)). Under `--max-age <s>`
402
+ it reuses a login a status read observed at most `<s>` seconds ago, so a
403
+ client polling every few seconds asks GitHub about once per `<s>`. Only
404
+ that display does: a schedule tick, `oats trigger poll` (with `--max-age`
405
+ too), `oats trigger run` and every other act that places or fires an
406
+ automation asks `gh` live. A login is reused only under the same `gh`
407
+ context: the same GitHub host, the same `gh` binary (as `PATH` finds it
408
+ from the deployment), the same set of token variables (`GH_TOKEN`,
409
+ `GITHUB_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN`: which are
410
+ set, never their values), the same `GH_HOST` and config directory, and an
411
+ unchanged `hosts.yml` there (a `gh auth login`, `logout` or `switch`
412
+ rewrites it). Only a successful answer is kept, never a token or its
413
+ digest; a failed one is not, and it ends the reuse of the success before
414
+ it. Within `<s>`, a token variable given another value or a token revoked
415
+ on GitHub still shows the login, as a head moved on the remote shows
416
+ unmoved. The display waits at most 5 s for `gh` (an act waits 30 s): a
417
+ `gh` that does not answer in time reads `owner-mismatch`, as one that is
418
+ not logged in does.
388
419
  - **When a head is not reused:** it is older than the flag allows (or dated
389
420
  more than 5 s in the future); it was observed through a different URL
390
421
  spelling of the same repository (ssh vs https) or for a different ref; its
@@ -3269,14 +3300,21 @@ its absence.
3269
3300
  `true` means the harness is running, using the same pane and shell-descendant
3270
3301
  rule as session inspection. A fallback shell is `false` with `runtimeState:
3271
3302
  "shell"`, even though the window remains; a dead pane or absent window is
3272
- `false`. A wrapper shell with a live non-shell descendant stays `true`;
3303
+ `false`. A wrapper shell with a live non-shell descendant stays `true`.
3304
+ `false` for a shell needs positive evidence: the process table holds the
3305
+ pane's own process as a shell and no non-shell process below it
3306
+ ([#1641](https://github.com/awebai/oats/issues/1641)); a table that cannot
3307
+ establish that reads `null` with the reason as `runtimeError`: one without
3308
+ the pane's process (a `ps` in another PID namespace, a pane respawned since
3309
+ tmux answered), one with a process in the pane that has no command name, or
3310
+ one with a line that is not a process when nothing non-shell was found.
3273
3311
  `null` with `runtimeState: "unreachable"` and the tmux error as
3274
3312
  `runtimeError` when that server or its panes cannot be read (including a
3275
3313
  window where OATS cannot tell which pane is the agent's
3276
3314
  ([which pane is the agent's](execution-targets.md#which-pane-is-the-agents)),
3277
- a session with two windows of the instance's name, or a failed
3278
- shell-descendant process scan; a window whose agent's pane is found reads by
3279
- that pane alone), and also when its socket
3315
+ a session with two windows of the instance's name, or a failed or
3316
+ inconclusive shell-descendant process scan; a window whose agent's pane is
3317
+ found reads by that pane alone), and also when its socket
3280
3318
  file is missing while a process works in the home or the process scan
3281
3319
  cannot run, `runtimeError` then naming the processes or the scan's error
3282
3320
  ([#624](execution-targets.md#missing-socket); with no process in the home
@@ -3878,6 +3916,206 @@ instance's own machine: the local command, with `--server <id>` added.
3878
3916
  `E_REMOTE_INCOMPATIBLE`, naming both and the host's version, before
3879
3917
  anything is sent. A name two homes share on the host is `E_AMBIGUOUS`.
3880
3918
 
3919
+ <a id="the-warm-reader"></a>
3920
+ ## The warm reader (`oats reader --stdio`)
3921
+
3922
+ Feature `warm-reader`, `readerApi: 1`. A client that polls a deployment can
3923
+ start one long-lived child, `oats reader --stdio`, and send it the poll's
3924
+ reads, `oats status --json` and `oats workspace status --json`, over its
3925
+ stdin and stdout instead of running the CLI for each one. The reader answers
3926
+ with the kernel's own read code, kept loaded. It is an accelerator of
3927
+ identical answers: whenever it is absent, refuses, times out or dies, the
3928
+ client runs that same read through the CLI, unchanged. The decisions are in
3929
+ the [design record](design/2026-10-29-warm-reader.md).
3930
+
3931
+ ```text
3932
+ oats reader --stdio
3933
+ ```
3934
+
3935
+ It takes no other argument: bare `oats reader`, or anything else after it,
3936
+ is `E_USAGE`.
3937
+
3938
+ - **Warm code, not warm data.** The reader keeps only loaded kernel code and
3939
+ install-derived constants (the kernel's code fingerprint, the parsed JSON
3940
+ schemas, the boot id). Every request reads the deployment afresh: instances
3941
+ spawned or retired by another process, an edited `oats-local.yaml` or
3942
+ lock, a dead session all show in the next answer exactly as in a CLI run.
3943
+ `--max-age` reuse is the CLI's own on-disk
3944
+ [observation reuse](#observation-reuse-feature-observe-max-age-oats-0311),
3945
+ unchanged.
3946
+ - **Same answer as the CLI.** For an accepted request, `exit` and `answer` are
3947
+ what `oats <argv>`, run by the same install with the same environment and
3948
+ with cwd = `--dir`, prints and exits with at that moment: the same envelope
3949
+ and schema versions, the same error codes and refusals, the same `null` and
3950
+ unknown facts. An environment that carries `OATS_RESOLUTION` or
3951
+ `OATS_DEPLOYMENT` is one of them: the reader starts, and answers each
3952
+ request with the CLI's `E_UNSUPPORTED_MODE`. Anything the reader cannot
3953
+ answer that way is a refusal, a frame of its own, on which the client runs
3954
+ the CLI: a client cannot tell the warm path from the fallback.
3955
+
3956
+ ### Starting it and the probe
3957
+
3958
+ - `oats version --json` lists feature `warm-reader` and `readerApi: 1` (the
3959
+ feature and API number convention). A client starts a reader only when the
3960
+ probe it holds lists both.
3961
+ - The client starts `oats reader --stdio` from the same binary, Node and
3962
+ environment it runs its CLI reads with.
3963
+ - The version rule is the CLI's own: a reader is trusted only when its
3964
+ version equals the probe's, which the client has already accepted under its
3965
+ normal range. There is no second rule. Remote routes are out: a reader
3966
+ answers reads of this machine's deployments only.
3967
+
3968
+ ### Wire format
3969
+
3970
+ UTF-8, one JSON object per line (`\n`), both directions. Frames are told
3971
+ apart by their keys. A client ignores unknown keys and any line that is no
3972
+ frame it knows (a request it then misses times out and falls back).
3973
+
3974
+ - **Hello** (reader to client, the first line, once every module the reads
3975
+ use is loaded, so a hello means ready):
3976
+
3977
+ ```json
3978
+ {"readerApi":1,"version":"<the kernel's version>","reads":["status","workspace status"]}
3979
+ ```
3980
+
3981
+ - **Request** (client to reader), at most 64 KiB a line:
3982
+
3983
+ ```json
3984
+ {"id":"<a string of at most 64 characters, or a safe integer>","argv":["status","--dir","/w","--max-age","60","--json"]}
3985
+ ```
3986
+
3987
+ Accepted: an argv the kernel's own hot-read classification
3988
+ (`lib/hot-reads.mjs`) names as one of `reads`, that includes `--json` and
3989
+ an absolute `--dir`. So the flags, [`--flag=value`](#flags) and the
3990
+ exclusion of `--help` are exactly the CLI's; `--team` or a bad `--max-age`
3991
+ get the CLI's own `E_BAD_ARGS` answer; `status --server` is another read
3992
+ and is refused. A relative, blank or missing `--dir`, or no `--json`, is
3993
+ refused. Other keys of a request are ignored.
3994
+ - **Answer** (reader to client):
3995
+
3996
+ ```json
3997
+ {"id":"…","exit":0,"answer":{"…":"…"},"stderr":"<text>"}
3998
+ ```
3999
+
4000
+ `answer` is the JSON value the CLI prints on stdout, an error envelope
4001
+ included. Equivalence is `exit` and `answer`. `stderr`, present only when
4002
+ there is some, is diagnostic text (the CLI's stderr for that read),
4003
+ informative only, never parsed and outside the equivalence. It is at most
4004
+ 8 KiB of UTF-8, cut at a character boundary, so that it never pushes an
4005
+ answer line over a client's bound.
4006
+ - **Refusal** (reader to client), never a CLI answer:
4007
+
4008
+ ```json
4009
+ {"id":"…","refused":{"code":"E_READER_UNSUPPORTED","message":"…"}}
4010
+ ```
4011
+
4012
+ `id` is `null` when the line's id cannot be read. The codes are used only
4013
+ here, never in an envelope:
4014
+
4015
+ | Code | When | Then the reader |
4016
+ |---|---|---|
4017
+ | `E_READER_BAD_REQUEST` | a line that is not a request: not one JSON object, an `id` that is neither a string of at most 64 characters nor a safe integer, an `argv` that is not an array of strings, a line over 64 KiB | answers the next request |
4018
+ | `E_READER_UNSUPPORTED` | an argv outside the accepted forms; a `--dir` the reader cannot make its working directory (a removed deployment), which the CLI then answers with its own failure | answers the next request |
4019
+ | `E_READER_STALE` | the install changed since the reader started ([The install stamp](#reader-install-stamp)) | refuses every queued request the same way, then exits 0 |
4020
+ | `E_READER_DEFECT` | an unexpected failure of the reader | writes the stack to its stderr and exits 1: per-request state may be half reset |
4021
+
4022
+ - Answers may arrive in any order: match them by `id`. This kernel answers
4023
+ one request at a time, in arrival order.
4024
+
4025
+ <a id="reader-install-stamp"></a>
4026
+ ### The install stamp
4027
+
4028
+ An install that changed under a reader (an upgrade, a Node upgrade) is never
4029
+ answered from the old code. The reader takes a stamp of its install before
4030
+ any of the kernel's own modules load (only the CLI's entry point and three
4031
+ small modules of Node built-ins load before it), so an install that changes
4032
+ while the reader starts is seen too:
4033
+ the install root directory's device and inode; device, inode, size and mtime
4034
+ of `package.json`, `bin/oats.mjs`, `package-catalog.json`, every file under
4035
+ `lib/`, `docs/*.schema.json`, each runtime dependency's `package.json`
4036
+ where it resolves at that moment (a dependency newly installed nearer the
4037
+ install moves it) and the Node binary (its real path); and the mtime of each
4038
+ directory under `lib/` and of `docs/` (a file added or removed). It takes the
4039
+ stamp again when a request starts and again just before that request's answer
4040
+ is written. Any difference, or a file gone (an npm global update replaces the
4041
+ package directory; a half-written install reads as changed too), refuses that
4042
+ request and every queued one with `E_READER_STALE`, and the reader exits 0.
4043
+ No hashing, no timers, no file watchers. A `PATH` symlink re-pointed at
4044
+ another install of the same version is invisible to any stamp: the client's
4045
+ binding of its reader to the probe record it started it for covers it.
4046
+
4047
+ ### Lifetime
4048
+
4049
+ The reader's lifetime is its client's. Its exit and signal handlers are
4050
+ installed once, at start.
4051
+
4052
+ | The reader exits | Status |
4053
+ |---|---|
4054
+ | on stdin's end or a read error on it (its client is gone) | 0 |
4055
+ | on `EPIPE` on stdout | 0 |
4056
+ | on `SIGTERM`, `SIGINT`, `SIGHUP` | 128 + the signal's number: 143, 130, 129 |
4057
+ | after `E_READER_STALE` | 0 |
4058
+ | after `E_READER_DEFECT` | 1 |
4059
+
4060
+ A request in flight when the reader ends is not answered, and its read session
4061
+ is closed on the way out, which kills its `git` children. A reader killed
4062
+ with `SIGKILL` leaves its `git` process groups to their own timeouts, as the
4063
+ CLI does. Its stdout carries protocol lines only: anything else written there
4064
+ goes to its stderr, and no child it runs inherits its stdout.
4065
+
4066
+ <a id="reader-working-directory"></a>
4067
+ ### The working directory
4068
+
4069
+ The reads read no working directory, but the programs they run by name
4070
+ (`tmux`, `git`) are found on `PATH`, and a relative or empty `PATH` entry
4071
+ resolves against the process's working directory, not the deployment's. So
4072
+ that it resolves as in a CLI run with cwd = `--dir`, the reader changes its
4073
+ working directory to the request's `--dir` for the read and back to its
4074
+ install root when the request ends, answered or failed: it never keeps a
4075
+ deployment directory that may be removed or unmounted. This depends on
4076
+ answering one request at a time. A reader that answers two at once must first
4077
+ give each child it runs its own working directory.
4078
+
4079
+ ### Client rules
4080
+
4081
+ - **Start.** Exactly as the client runs its CLI reads: the same realpath'd
4082
+ binary, the same Node, the same environment, no shell. Stdin and stdout
4083
+ piped, stderr ignored or drained with a bound (an undrained pipe would
4084
+ block the reader). Reads issued before the hello arrives go to the CLI: no
4085
+ tick waits on the reader's start.
4086
+ - **Trust.** Only after a hello, within the CLI read's timeout, with
4087
+ `readerApi === 1`, a `version` equal to that of the probe that gated it,
4088
+ and the read in `reads`. A mismatch: end the reader and use the CLI until
4089
+ the client's probe changes; no retries. A reader is bound to the probe
4090
+ record it was started for: a read under another record ends it, and the
4091
+ next one starts for the new record.
4092
+ - **What goes to the reader.** Background reads (`--max-age` above 0). Live
4093
+ reads (`--max-age 0`: after a mutation, an admission, a probe change) go to
4094
+ the CLI, so they never queue behind the reader's one-at-a-time answers.
4095
+ - **Refusals.** `E_READER_UNSUPPORTED` or `E_READER_BAD_REQUEST`: that read
4096
+ goes to the CLI, and the reader is kept. `E_READER_STALE`: the install
4097
+ changed; the read goes to the CLI, the client probes again and starts a
4098
+ fresh reader on a later tick (not counted as a failure). A client that
4099
+ never probes again uses the CLI for the rest of its session.
4100
+ - **Failures**, which count toward giving up: an exit without an answer, a
4101
+ hello timeout, a request timeout, `E_READER_DEFECT`. The reads in flight go
4102
+ to the CLI; a new reader starts on a later tick with backoff (1 s, doubling
4103
+ to 5 min); after 5 consecutive failures without an answer, the CLI until
4104
+ the client's probe changes, or until its session ends.
4105
+ - **Timeout.** A request's deadline is the CLI read's own timeout, counted
4106
+ from when it becomes the oldest unanswered request: time in the queue does
4107
+ not count.
4108
+ - **Answers.** The client bounds the raw answer line by the CLI read's output
4109
+ limit before parsing it, parses it once, and passes `answer` and `exit`
4110
+ through the same validation as the CLI's stdout and exit status: an error
4111
+ envelope with a nonzero `exit` is handled exactly as from the CLI. The
4112
+ reader's stderr, the answer's field and its own, is never forwarded, as
4113
+ the CLI read's stderr is not. A client never
4114
+ treats the reader as authority beyond what the same CLI read would be.
4115
+ - **End.** The app ends its reader when it quits: closing its stdin is
4116
+ enough, and `SIGTERM` works too. The reader's lifeline is the app's
4117
+ exclusive hold of its stdin: the app's death closes it.
4118
+
3881
4119
  <a id="instance-git-state-oats-instance-gitdiff-instancegitapi-1-oats-0247"></a>
3882
4120
  ## Git and diff
3883
4121
 
@@ -56,7 +56,16 @@ agents' tmux (ssh, cron, a plain terminal) sees the same liveness as `session
56
56
  inspect`. `running` means the harness is running, not merely that its window
57
57
  exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
58
58
  a retained dead pane also reads `false`. A wrapper shell with a live non-shell
59
- descendant still reads `true`. Status shares session inspection's pane rule,
59
+ descendant still reads `true`. tmux names the pane's foreground process group,
60
+ which is the launch's own shell while the harness runs as its child, so a
61
+ running instance is usually read through this process scan. `false` needs
62
+ positive evidence of the fallback prompt: the process table holds the pane's
63
+ own process as a shell and no non-shell process below it. A table that cannot
64
+ establish that (no pane process in it, as for a `ps` in another PID
65
+ namespace; a process in the pane with no command name; a line that is not a
66
+ process, when nothing non-shell was found) reads `running: null` with its
67
+ reason, and `session inspect` answers `E_SESSION_UNAVAILABLE`
68
+ ([#1641](https://github.com/awebai/oats/issues/1641)). Status shares session inspection's pane rule,
60
69
  with one batched pane read per socket/session and one lazy process scan across
61
70
  all panes that need it. It reads the agent's pane alone, so a window with
62
71
  another pane reads as one without it
@@ -1470,7 +1479,7 @@ oats session attach --home /abs/home --detach-key 'C-\'
1470
1479
  for input, nor that it consumed a wake, and it does not prove which
1471
1480
  executable runs if a process inside the pane was replaced. When the backend
1472
1481
  cannot be read, a required process-table read for an explicitly labelled
1473
- shell fails, the pane answer is
1482
+ shell fails or cannot establish a fallback shell (above), the pane answer is
1474
1483
  malformed, or OATS cannot tell which of the window's panes is the agent's,
1475
1484
  inspect is an error as before, never `running: false`.
1476
1485
  That includes a tmux server that is gone (`no server running on` its