@awebai/oats 0.69.4 → 0.69.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/bin/oats.mjs +141 -364
  2. package/docs/configuration.md +12 -0
  3. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  4. package/docs/design/2026-10-29-warm-reader.md +261 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +258 -13
  7. package/docs/execution-targets.md +36 -5
  8. package/docs/implementation.md +34 -9
  9. package/docs/integrations.md +2 -2
  10. package/docs/knowledge.md +18 -8
  11. package/docs/named-test-runs.md +4 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-notes/v0.69.5.md +146 -0
  15. package/docs/release-notes/v0.69.6.md +165 -0
  16. package/docs/schedules.md +8 -1
  17. package/docs/tui.md +23 -5
  18. package/docs/upgrading.md +20 -5
  19. package/docs/workspaces.md +2 -2
  20. package/lib/agents-root.mjs +51 -0
  21. package/lib/argv.mjs +41 -0
  22. package/lib/automation-api.mjs +7 -0
  23. package/lib/automation-scope.mjs +37 -0
  24. package/lib/automations.mjs +63 -12
  25. package/lib/captured-context.mjs +12 -0
  26. package/lib/compile-cache.mjs +36 -0
  27. package/lib/core.mjs +39 -1348
  28. package/lib/deployment-path.mjs +127 -0
  29. package/lib/deployments.mjs +2 -2
  30. package/lib/drift.mjs +95 -0
  31. package/lib/hot-reads.mjs +137 -0
  32. package/lib/install-stamp.mjs +61 -0
  33. package/lib/instance-address.mjs +21 -0
  34. package/lib/instance-events.mjs +8 -6
  35. package/lib/instance-lifecycle.mjs +4 -16
  36. package/lib/instance-listing.mjs +738 -0
  37. package/lib/instance-resolution.mjs +5 -166
  38. package/lib/kernel-features.mjs +10 -0
  39. package/lib/local-edit.mjs +1 -1
  40. package/lib/local-inputs.mjs +3 -0
  41. package/lib/materialize.mjs +2 -87
  42. package/lib/member-clone.mjs +192 -0
  43. package/lib/package-catalog.mjs +93 -0
  44. package/lib/packages.mjs +4 -24
  45. package/lib/read-call.mjs +143 -0
  46. package/lib/reader.mjs +203 -0
  47. package/lib/remote.mjs +47 -6
  48. package/lib/reserved-launch-env.mjs +20 -0
  49. package/lib/resolved-deployment.mjs +13 -5
  50. package/lib/roster-read.mjs +199 -0
  51. package/lib/schedule.mjs +5 -29
  52. package/lib/semver.mjs +12 -0
  53. package/lib/servers.mjs +10 -12
  54. package/lib/session-end.mjs +3 -2
  55. package/lib/session-input.mjs +35 -11
  56. package/lib/session-inspect.mjs +219 -0
  57. package/lib/soul-listing.mjs +216 -0
  58. package/lib/status-words.mjs +30 -0
  59. package/lib/version.mjs +9 -0
  60. package/lib/workspace-read.mjs +160 -0
  61. package/lib/write-file-atomic.mjs +28 -0
  62. package/package-catalog.json +4 -4
  63. package/package.json +1 -1
  64. package/packages/client/cli-locator.mjs +1 -0
  65. package/packages/client/cli-probe-contract.mjs +4 -2
  66. package/packages/client/deployment-observer.mjs +8 -3
  67. package/packages/client/deployment-panel.mjs +17 -1
  68. package/packages/client/deployment-read-cli.mjs +48 -27
  69. package/packages/client/own-codes.mjs +3 -0
  70. package/packages/client/warm-reader.mjs +241 -0
  71. package/packages/tui/lib/client.mjs +2 -1
  72. package/packages/tui/lib/read.mjs +59 -11
  73. package/packages/tui/lib/store.mjs +7 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -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
@@ -3332,7 +3370,8 @@ its absence.
3332
3370
  `lost` (the host went down, its tmux server died, or the harness was killed
3333
3371
  by a signal: the sweep brings it back when it can vouch for the loss,
3334
3372
  [Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
3335
- `oats instance stop`, Desktop's Stop) or `exited` (the harness ended by
3373
+ `oats instance stop`, Desktop's Stop, or an `oats session restart` whose
3374
+ relaunch did not happen) or `exited` (the harness ended by
3336
3375
  itself: `/exit`, its own error). Present only on a row that reads
3337
3376
  `running: false` and records `launched: true`, a row at its fallback shell
3338
3377
  (`runtimeState: "shell"`) included; absent while it runs or reads unknown
@@ -3621,6 +3660,12 @@ route target:
3621
3660
  whose kernel predates the feature, and a saved route the host did not list
3622
3661
  carry no key ([`sameWork`](#row-same-work)). `oats status --server <id>
3623
3662
  --json` relays the host's answer verbatim, `sameWork` included.
3663
+ - **`sessionEnd`** (feature `session-resume`; relayed from 0.69.5) is on a row only
3664
+ when the host's row has the key, with the host's value: a host whose kernel
3665
+ predates the feature, a row the host reports without it (one that runs,
3666
+ for example), and a saved route the host did not list carry none. Its
3667
+ meaning and when the host sends it are the [local row's](#row-session-end).
3668
+ A value that is not `lost`, `stopped` or `exited` drops the key.
3624
3669
  - **`addressable`** (0.31): `true` for every row the host reports. Routed
3625
3670
  session and lifecycle commands reach it by `--home`, or by name when the
3626
3671
  name is unique on the host ([addressing](servers.md#run-there); a shared
@@ -3871,6 +3916,206 @@ instance's own machine: the local command, with `--server <id>` added.
3871
3916
  `E_REMOTE_INCOMPATIBLE`, naming both and the host's version, before
3872
3917
  anything is sent. A name two homes share on the host is `E_AMBIGUOUS`.
3873
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
+
3874
4119
  <a id="instance-git-state-oats-instance-gitdiff-instancegitapi-1-oats-0247"></a>
3875
4120
  ## Git and diff
3876
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
@@ -1185,6 +1194,16 @@ it ends, before it ends it, so a home it was retiring reads `stopped`, never
1185
1194
  stop record itself cannot be written (a full disk) and the retire then fails
1186
1195
  as well: that home reads `lost`, as it did before 0.69.2.
1187
1196
 
1197
+ `oats session restart` records the stop of the session it replaces the same
1198
+ way, before it asks the harness to end (#1601): a restart whose relaunch
1199
+ fails, or that dies between the stop and the relaunch, leaves a home that
1200
+ reads `stopped`, so no resume starts again the launch it was replacing. The
1201
+ relaunch records a new start, which that record does not name. A restart
1202
+ whose stop is refused (`E_SESSION_STOP_FAILED`, the harness still there after
1203
+ the grace) keeps its record: should that harness die later, the home reads
1204
+ `stopped`, not `lost`. A restart of a home that does not run stops nothing and
1205
+ records nothing, so it keeps its reading.
1206
+
1188
1207
  #### How a session's end is read
1189
1208
 
1190
1209
  A launched home that does not run reads one of three ends, `sessionEnd` on
@@ -1198,10 +1217,18 @@ for its current start (`startId` in `instance.json`):
1198
1217
  | an exit marker that names it with a signal's status (128 and up: the harness alone was killed, an out-of-memory kill for example) | `lost` | when the sweep can vouch for the loss ([below](#which-losses-come-back)) |
1199
1218
  | neither (the host went down, or the tmux server died under the live harness) | `lost` | when the sweep can vouch for the loss |
1200
1219
 
1220
+ In text, `oats status`, `oats status --server <id>` and `oats server roster`
1221
+ print a `lost` row as `LOST`, where a `stopped` or `exited` row, or one
1222
+ without `sessionEnd`, prints `idle`, with one line under it naming the way
1223
+ back: `oats session start --resume --home <home>`, or the next sweep (`oats
1224
+ session resume`, which OATS Desktop and `oats tui` run when they open) when
1225
+ it can vouch for the loss. Both act on this machine's homes only, so a row
1226
+ of another host names the host to run them on.
1227
+
1201
1228
  The window a spawn or a start makes writes the exit marker,
1202
1229
  `.oats-start-exited`, when the harness exits; `oats instance stop` writes its
1203
- record, `.oats-stop.json`, and so does a retire, before it ends the window
1204
- (0.69.2). Both are kernel-private files of the home, not a
1230
+ record, `.oats-stop.json`, and so do a retire, before it ends the window
1231
+ (0.69.2), and `oats session restart`, before it stops the harness (#1601). Both are kernel-private files of the home, not a
1205
1232
  contract: read `sessionEnd`. A shutdown kills the window's shell with the
1206
1233
  harness, so a lost session leaves no marker. A home spawned before 0.69 and
1207
1234
  never restarted since names no start: it reads `stopped` only after a stop,
@@ -1325,13 +1352,17 @@ resumes it. So:
1325
1352
  - a loss first seen a day ago or more, or a session that died before any read
1326
1353
  of OATS saw it run, stays down.
1327
1354
 
1328
- Two limits follow from reading only what OATS saw:
1355
+ Three limits follow from reading only what OATS saw:
1329
1356
 
1330
1357
  - **After upgrading to 0.69**, open OATS Desktop or `oats tui`, or run `oats
1331
1358
  status`, once before you restart the computer, or nothing from before the
1332
1359
  upgrade comes back.
1333
1360
  - A whole boot with no OATS read leaves that boot unknown: what ran in it and
1334
1361
  was lost there is not resumed.
1362
+ - Clause 4 does not reach across a reboot. On a computer where nothing read
1363
+ OATS for more than a day before a restart (every agent already down, no
1364
+ client open), the first sweep after the restart can bring back a session
1365
+ that was lost during that quiet spell.
1335
1366
 
1336
1367
  Without a boot id (neither Linux nor macOS: both have one), clause 4 applies
1337
1368
  to every loss and the 3-resumes-per-boot guard (below) is off.
@@ -1448,7 +1479,7 @@ oats session attach --home /abs/home --detach-key 'C-\'
1448
1479
  for input, nor that it consumed a wake, and it does not prove which
1449
1480
  executable runs if a process inside the pane was replaced. When the backend
1450
1481
  cannot be read, a required process-table read for an explicitly labelled
1451
- shell fails, the pane answer is
1482
+ shell fails or cannot establish a fallback shell (above), the pane answer is
1452
1483
  malformed, or OATS cannot tell which of the window's panes is the agent's,
1453
1484
  inspect is an error as before, never `running: false`.
1454
1485
  That includes a tmux server that is gone (`no server running on` its
@@ -23,7 +23,10 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
23
23
  and may never add one: with a dependency it could no longer ship in this
24
24
  tarball.
25
25
  - **`@awebai/oats-pi`** (`packages/pi/`): a thin pi adapter that exposes an
26
- instance's own resources. It registers no agent tools.
26
+ instance's own resources. It registers no agent tools. It ships no kernel:
27
+ `extension/core-loader.mjs` imports the kernel that launched the instance,
28
+ through the home's `oats` link, before any PATH or global lookup (the
29
+ order is in [its README](../packages/pi/README.md)).
27
30
  - **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
28
31
  `oats.support` and `oats.knowledge-theory` capabilities and the
29
32
  `knowledge-theory-expert` soul,
@@ -49,9 +52,13 @@ from it, and the test lists the stable surface a second client may import.
49
52
  layers that each do one thing. `lib/term/` is the terminal: the key parser,
50
53
  cell widths, safe text, the screen and the guard that restores the terminal;
51
54
  only the screen and the guard write an escape byte. `lib/read.mjs` is every
52
- effect of reading: for each deployment opened in a run it runs the kernel
53
- of the same install and the shared liveness collector as children, through
54
- the shared observer and refresh loop; it runs that kernel's read of the
55
+ effect of reading: for each deployment opened in a run it reads through
56
+ the shared observer and refresh loop, its background reads through one
57
+ warm `oats reader --stdio` of the kernel of the same install (the shared
58
+ `createWarmReader`), every other read through that kernel as a child, and,
59
+ for a kernel without feature `status-liveness`, the shared liveness
60
+ collector as a child too; a void cycle's reads are answered at once,
61
+ the warm reader's included; it runs that kernel's read of the
55
62
  other machines (`oats server roster --json`), one at a time and awaited by
56
63
  no cycle; it ends every read child and lets changes finish; and it makes the one look at the file
57
64
  system the workspace switcher needs (whether a picked row is a deployment).
@@ -71,7 +78,7 @@ and the rules its tests pin.
71
78
 
72
79
  | path | contents |
73
80
  |---|---|
74
- | `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs |
81
+ | `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs. Its only static imports are Node built-ins and two dependency-free modules, `lib/compile-cache.mjs` and `lib/hot-reads.mjs`: it turns Node's compile cache on first, then imports the kernel and `yaml` with top-level `await import()`, in their order, because static imports are all parsed and linked before a module's body runs. A hot read (`version`, `session inspect`, `status`, `workspace status`, `instance events`, `instance waiting clear`, given only their own flags) imports only the leaves it uses, never `core.mjs` ([`hot-reads.mjs`](#kernel-modules)); every other command imports every module. A hot read takes its names from `lib/hot-reads.mjs`: a name newly used on a hot read's path must be listed there, under its import line, or its first use throws (a tripwire), and `test/cli-hot-reads.test.mjs` pins what each hot read must not load |
75
82
  | `lib/` | the kernel (below) |
76
83
  | `injects/` | the kernel and work-mode instruction blocks composed into every instance |
77
84
  | `skills/` | bootstrap skills shipped with the kernel |
@@ -96,6 +103,15 @@ and the rules its tests pin.
96
103
  | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
97
104
  | `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
98
105
  | `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
106
+ | `compile-cache.mjs` | the CLI's Node compile cache (awebai/oats#1630): `$OATS_HOME_DIR/compile-cache`, made 0700, unless the caller's `NODE_COMPILE_CACHE` or `NODE_DISABLE_COMPILE_CACHE` decides; any failure is no cache and prints nothing, and `NODE_COMPILE_CACHE` is never put in the environment children inherit ([configuration](configuration.md#the-compile-cache)). Node built-ins only; kernel-private, not in `./core` |
107
+ | `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630), and the warm reader's start (`oats reader --stdio`, whose reads `reader.mjs` imports itself): each one's form (its words and the flags it takes) and, for each import line of `bin/oats.mjs`, the leaves it loads in that line's place; a line it does not list loads nothing, and any other argv loads everything. A name a read does not list is a tripwire: destructuring it is free, and any use throws a `HotReadUnlisted` defect naming the read, the line and the name. `test/cli-hot-reads.test.mjs` runs each read with a load hook and pins what it must not load. Kernel-private, not in `./core` |
108
+ | `roster-read.mjs`, `workspace-read.mjs`, `read-call.mjs` | the deployment reads (awebai/oats#1630): `oats status` (`roster-read.mjs`: the roster, its drift and its workspace identity) and `oats workspace status` (`workspace-read.mjs`: members, packages, automations, the desktop facts, and the rows `oats sync` reports too), one implementation behind the CLI and a process that answers them many times. Each has an answer function (`statusAnswer`, `workspaceStatusAnswer`: `{ exit, answer, stderr }`, `answer` the JSON the CLI prints, a refusal included) and a data function (`statusView`, `workspaceStatusView`) bin's text renderer reads. `read-call.mjs` is one call's scope: it takes an explicit context (the absolute `dir`, `maxAge`, the caller's read session, the cache, an optional deployments observer), resets at its start every piece of module-level state the reads can reach (`READ_STATE`; `test/read-call-state.test.mjs` scans the reads' import closure and fails on a binding with no row), answers refusals as envelopes, and drains the session's notices. Within one call, two pieces of work are not repeated: `listInstances` hands the records it read to the rest of the read (`records`: `legacyCapturedHomes` and the waiting read take them instead of parsing them again), and `workspace status` asks git for each member clone's remotes once (`remotes`, shared by the automation scope and the desktop facts); both are maps the read makes and drops, never module state. A call registers no process listener, closes no session and reads no argv or cwd: the CLI passes `commandSession` (created at the first remote read, with its exit and signal listeners) and closes it at the end of the command, as for every verb. The read part of the dispatch is there too (`parseMaxAge`, `readBudget`, `callSession`); `test/read-call-equivalence.test.mjs` answers both reads many times in one process and compares each answer with a fresh CLI run's. Leaves: never `core.mjs`. Kernel-private, not in `./core` |
109
+ | `reader.mjs` | `oats reader --stdio`, the warm reader (awebai/oats#1630; [the contract](desktop-cli-api.md#the-warm-reader), [the decisions](design/2026-10-29-warm-reader.md)): a client's child that answers `oats status --json` and `oats workspace status --json` on its stdin and stdout, many times, through `read-call.mjs` and the two answer functions, never a copy of them. It loads every module the reads import lazily (`PRELOAD`) before its hello; classifies a request with `hot-reads.mjs` `hotRead` and expands its flags with `argv.mjs`, then runs the dispatch's read part in the CLI's order (the flag syntax, `--max-age`, the inherited context), so a refusal there is the CLI's own answer; answers one request at a time, in arrival order, each with its own read session, closed at its end, and its deployments observer; changes its working directory to the request's `--dir` for the read and back to the install root after, because the programs the reads run by name resolve a relative `PATH` entry against it (a second lane must first give each child its own cwd). It compares `install-stamp.mjs`'s stamp, taken by `bin` before the kernel loaded, when a request starts and before its answer is written: a change refuses `E_READER_STALE` and exits. Its stdout carries protocol lines only (other writes go to stderr); a request in flight at exit has its session closed from the `exit` handler. `test/reader-protocol.test.mjs` pins the protocol and `PRELOAD` against the reads' closure. `oats reader --stdio` is a hot-read form, so `bin` loads only its dispatch's leaves for it, never `core.mjs` (`test/cli-hot-reads.test.mjs`). Kernel-private, not in `./core`. Dependency-free |
110
+ | `install-stamp.mjs` | the warm reader's install stamp: `stat` of the install's code and data (package.json, bin/oats.mjs, the catalog, every file under lib/, the docs schemas, each runtime dependency's package.json where it resolves now, the Node binary) as one string. Node built-ins only: `bin` imports it statically and takes the reader's baseline before any kernel module loads; `reader.mjs` compares each request against it |
111
+ | `argv.mjs` | how the kernel reads `--flag=value` ([Flag syntax](desktop-cli-api.md#flags)): `expandInlineValues`, which the CLI's dispatch runs once on its argv and the reader on each request's, so both give a malformed flag the same `E_BAD_ARGS`, and `flagValue`, a flag's value in an expanded argv. Kernel-private, not in `./core`. Dependency-free |
112
+ | `kernel-features.mjs` | `KERNEL_FEATURES`, the features this kernel implements: `features` in `version --json` and in `status --json`; `READER_API`, the warm reader's protocol number (`readerApi` in `version --json` and in the reader's hello). Kernel-private, not in `./core` |
113
+ | `captured-context.mjs` | the refusal (`E_UNSUPPORTED_MODE`) of an environment that carries `OATS_RESOLUTION` or `OATS_DEPLOYMENT`, which the dispatch asks for every command but `version` and `reader`; the reader asks it for each request instead, so it starts and answers each read as the CLI would. Dependency-free |
114
+ | `version.mjs`, `deployment-path.mjs`, `write-file-atomic.mjs`, `agents-root.mjs`, `soul-listing.mjs`, `instance-address.mjs`, `session-inspect.mjs`, `instance-listing.mjs`, `drift.mjs`, `package-catalog.mjs`, `member-clone.mjs`, `reserved-launch-env.mjs`, `automation-scope.mjs`, `automation-api.mjs`, `semver.mjs` | the leaves the hot reads load instead of the modules that re-export them (awebai/oats#1630): the version; the canonical deployment path; the atomic file write; the agents root; souls and instance homes; `resolveInstance`; `inspectInstanceSession`; `listInstances` and the status rows; soul and module drift; the official package catalog; discovery and member clones; the reserved launch environment; the automation scope; the automation API versions; `compareSemver`. Each name is still exported, under the same name, from the module it left (`core.mjs`, `packages.mjs`, `instance-lifecycle.mjs`, `materialize.mjs`, `instance-resolution.mjs`, `schedule.mjs`, `automations.mjs`, `servers.mjs`), so `./core` is unchanged (`test/core-exports.test.mjs`), and no leaf imports `core.mjs` or the module it left. Code a hot read reaches goes in a leaf, never in `core.mjs` |
99
115
  | `upgrade-state.mjs` | upgrade receipt state and the partial-upgrade guard used before session start; receipts remain lifecycle state, and provider adoption stays in the module's upgrade hook |
100
116
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
101
117
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
@@ -127,14 +143,15 @@ and the rules its tests pin.
127
143
  | `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
128
144
  | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
129
145
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
146
+ | `status-words.mjs` | the word `oats status`, `oats status --server` and `oats server roster` print for an instance row (RUNNING, LOST, idle, unknown, RETIRING; the roster keeps its own suffixes) and the line under a LOST row that names the way back; rows in, strings out, the JSON untouched |
130
147
  | `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
131
148
  | `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
132
149
  | `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
133
150
  | `file-pieces.mjs` | a regular file's bytes read in pieces of 1 MiB (`readFilePieces`, `hashFile`, and `readFileUpTo` for a home's `instance.json`, read whole up to 16 MiB for its neutral form), for every digest of the retire path: what a digest holds of a file is bounded whatever its size (Node reads no file over 2 GiB whole), and a file is read for the size it had when it was opened. One that ends before that size refuses with `E_WORK_INSPECTION_FAILED` |
134
- | `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
151
+ | `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; a shell-labelled pane is a fallback shell only when that scan shows the pane's own process as a shell with no non-shell descendant, and a scan that cannot show it throws its reason (unknown, never idle: #1641); `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
135
152
  | `servers.mjs` | routing commands to a registered server |
136
153
  | `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; a root under a temporary directory (`underTemporaryDirectory`, awebai/oats#1397) is never auto-added; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
137
- | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`core.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
154
+ | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`agents-root.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. A process that answers many reads sets its observer with `atExit: false` and settles it at the end of each read (`read-call.mjs`), which also forgets what the last one reported (`resetResolvedDeployment`). Dependency-free |
138
155
  | `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
139
156
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
140
157
  | `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
@@ -331,7 +348,7 @@ gets the plain per-call behaviour. Within a session:
331
348
  exit hook (`closeNow`), and the system reaps them once the process is gone;
332
349
  - a session may have a `deadline` (`READ_REMOTE_BUDGET_MS`, 12 s after it
333
350
  starts): the CLI gives one to `status` and `workspace status` only
334
- (`readBudgetMs`; `OATS_READ_REMOTE_BUDGET_MS` is a test and ops override,
351
+ (`read-call.mjs` `readBudget`; `OATS_READ_REMOTE_BUDGET_MS` is a test and ops override,
335
352
  not a contract). Every
336
353
  remote step then gets what is left of it instead of its own default: each
337
354
  git call's timeout (`sessionExec`: ls-remote, fetch, ls-tree, the cache's
@@ -484,7 +501,15 @@ atomically, a corrupt one is a miss, and `pruneStores` bounds the store
484
501
  (`PARSED_LIMITS`, least recently used first). `--max-age` adds the observation
485
502
  store `<cache>/.observed/` ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)):
486
503
  one record per (repo key, ref args, url digest), so two spellings of one repo
487
- keep a record each; the url itself is never written. Adding a cached item
504
+ keep a record each; the url itself is never written. Beside it,
505
+ `<cache>/.observed-facts/` holds the remote facts that are not heads
506
+ (`factObservation`): today the `gh` login `workspace status` places automations
507
+ with for display ([the `gh` login, display only](desktop-cli-api.md#the-gh-login-display-only)).
508
+ A record is named by the digest of its fact's context (`ghLoginParts` in
509
+ `automations.mjs`: never a token value) and holds only the answer and when it
510
+ was observed; only `workspace-read.mjs` passes the reuse to `ghLogin` (its
511
+ `lookup`, with the display's 5 s wait), so a tick, a poll or a run always asks
512
+ `gh` live. `pruneStores` bounds both stores alike. Adding a cached item
488
513
  means choosing an item name unique to its producer (the item string its
489
514
  call site passes to `memoAtCommit`, or to `atCommit` in `workspace.mjs`) and
490
515
  adding it to `test/parsed-cache.test.mjs`; `test/read-path-scale.test.mjs` pins the member
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.5.0
44
- oats.aweb: v1.32.0
43
+ oats.okf: v5.7.0
44
+ oats.aweb: v1.32.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults: