@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.
- package/bin/oats.mjs +78 -320
- 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 +250 -12
- package/docs/execution-targets.md +11 -2
- package/docs/implementation.md +26 -8
- package/docs/integrations.md +1 -1
- package/docs/knowledge.md +14 -7
- package/docs/named-test-runs.md +4 -0
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.69.6.md +165 -0
- package/docs/schedules.md +8 -1
- package/docs/tui.md +21 -4
- package/docs/upgrading.md +9 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +41 -0
- package/lib/automation-scope.mjs +6 -4
- package/lib/automations.mjs +61 -11
- package/lib/captured-context.mjs +12 -0
- package/lib/hot-reads.mjs +21 -15
- package/lib/install-stamp.mjs +61 -0
- package/lib/instance-events.mjs +8 -6
- package/lib/instance-listing.mjs +13 -5
- package/lib/kernel-features.mjs +10 -0
- package/lib/local-edit.mjs +1 -1
- package/lib/local-inputs.mjs +3 -0
- package/lib/member-clone.mjs +15 -11
- package/lib/read-call.mjs +143 -0
- package/lib/reader.mjs +203 -0
- package/lib/remote.mjs +47 -6
- package/lib/resolved-deployment.mjs +12 -4
- package/lib/roster-read.mjs +199 -0
- package/lib/session-input.mjs +35 -11
- package/lib/workspace-read.mjs +160 -0
- package/package-catalog.json +2 -2
- 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/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.
|
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).
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -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.
|
|
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
|
|
348
|
-
everywhere; `reused` is `true` when any
|
|
349
|
-
|
|
350
|
-
|
|
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:**
|
|
380
|
-
|
|
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
|
|
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`.
|
|
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
|