@awebai/oats 0.69.2 → 0.69.4

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.
@@ -6438,7 +6438,7 @@ TUI decide, run and read it the same way.
6438
6438
  `lostLocalHomes` keeps a local row's absolute `home` when its `sessionEnd`
6439
6439
  says the session was lost and it is not running; it is the one place that
6440
6440
  reads `sessionEnd`'s meaning. There is no timer and no queue.
6441
- - After a sweep that a status read started completes (quiet or a notice),
6441
+ - After a sweep that a status read started completes (it reads `answered`),
6442
6442
  every instance it was started for waits until it changes: it runs, or it is
6443
6443
  no longer lost. A busy, failed or unsupported sweep, or a plan, settles
6444
6444
  nothing. A home a read releases while the sweep runs is settled by neither
@@ -6453,23 +6453,15 @@ TUI decide, run and read it the same way.
6453
6453
  - `cli()` gives the accepted probe or null, or a promise of either, and is
6454
6454
  asked at each would-be start: the sweep runs only when `resumeSupported`
6455
6455
  holds. When it does not, nothing runs and the floor does not move.
6456
- - Before reading an answer, it drops each `refused` row whose
6457
- `(home, reason, code)` an earlier sweep of this trigger already reported,
6458
- so a standing refusal is reported once. A home released (above) forgets its
6459
- reported refusals: refused again after it recovered, it is news. Every other
6460
- row is kept. The same goes for the result's own `warnings` (about the host):
6461
- one a notice of this trigger showed is left out of later answers by its
6462
- exact string, for the whole run; one only a quiet sweep carried stays news.
6463
- - `onReading(reading)` is called for every finished sweep, whatever the
6464
- reading. `launch()` and `observed()` never throw or reject; a `run` that
6456
+ - `read` is given the run's envelope itself, and `onReading(reading)` is
6457
+ called for every finished sweep, whatever the reading. `launch()` and `observed()` never throw or reject; a `run` that
6465
6458
  rejects reads as `failed`, `E_CLI_FAILED`. `dispose()` drops later readings
6466
6459
  and cancels nothing: a sweep in flight runs to its end.
6467
6460
 
6468
6461
  The Desktop shows nothing of a reading (the product owner, 2026-10-27): its
6469
6462
  main process writes a `failed` reading's code to its log in one line and drops
6470
- every other reading, a `notice` included. The TUI says nothing of a reading
6471
- either: a `notice` or a `quiet` reading asks it for a live read, and every
6472
- other reading for nothing
6463
+ every other reading. The TUI says nothing of a reading either: an `answered`
6464
+ reading asks it for a live read, and every other reading for nothing
6473
6465
  ([Resuming lost sessions](tui.md#resuming-lost-sessions)).
6474
6466
 
6475
6467
  **The runner**, `runResumeSweep` (`packages/client/session-resume-cli.mjs`):
@@ -6501,36 +6493,19 @@ other reading for nothing
6501
6493
  reaches the answer.
6502
6494
 
6503
6495
  **The reader**, `readResumeSweep` (`packages/client/session-resume.mjs`),
6504
- gives one of five readings: `unsupported` (nothing ran), `busy`
6505
- (`E_RESUME_BUSY`), `failed` with a code, `quiet`, or `notice` with a summary.
6506
- A plan answer (`plan: true`) is quiet.
6507
-
6508
- - The summary is facts: per row its instance, its deployment and its outcome's
6509
- reason, never a word of the kernel's text. `already-running` and `skipped`
6510
- rows are counted nowhere. A notice exists only when a row is `resumed`,
6511
- `fresh`, `blocked` or `refused`. Unchecked deployments are lines inside such
6512
- a notice, never a notice on their own; a deployment the kernel reports as
6513
- `opted-out` (an older kernel) reads as unchecked, with no reason.
6514
- - It is tolerant. A row without a string `instance` and `deployment`, with an
6515
- unknown `outcome`, or whose name the display filter withholds or empties, is
6516
- dropped. An unknown `reason` under a known outcome is read as no reason and
6517
- worded generically. A refusal's `code` is kept only when it matches
6518
- `^E_[A-Z0-9_]{1,64}$`.
6519
- - The result's own `warnings`, about the host and not one home, are the
6520
- summary's `host` (`{warnings, omitted}`, always present), kept and cut as a
6521
- row's are (below). They never make a notice alone; a notice shows them after
6522
- the unchecked deployments, under "OATS says about this computer:".
6523
- - A row's `warnings` are kept whole and in order, each as one display line
6524
- (`displayLine`), and cut by position only, at the bounds of
6525
- `launchFlagIgnored` (16 lines, 4096 UTF-16 units; `boundedWarnings`,
6526
- `packages/client/launch-prompt-outcome.mjs`). No warning is picked, matched
6527
- or dropped by its words.
6528
- - A refused row's `message` is the kernel's prose. It is shown only after
6529
- "OATS says:", attributed, through the display filter, and never matched.
6530
- - The summary keeps at most 100 rows, in the answer's order, and counts the
6531
- rest. The headline counts the real totals. `resumeSummaryFact` is the
6532
- summary's decoder at a boundary, and `resumeNotice` writes the headline and
6533
- the Details in the clients' own words (the TUI's line).
6496
+ gives one of four readings: `unsupported` (`E_CLI_UNAVAILABLE` or
6497
+ `E_RESUME_FEATURE`: nothing ran), `busy` (`E_RESUME_BUSY`), `failed` with a
6498
+ code, or `answered`. A reading carries nothing of the answer's rows or words.
6499
+
6500
+ - `answered` is every `ok: true` answer whose result is the sweep's document,
6501
+ a plan (`plan: true`) included. A plan started nothing, so it completes
6502
+ nothing: its snapshot and its rows settle no home (`sweepCompleted`,
6503
+ `sweepSettlement`).
6504
+ - `failed` carries the refusal's code when it matches `^E_[A-Z0-9_]{1,64}$`,
6505
+ else `E_CLI_PROTOCOL`. An `ok: true` answer that is not the document (no
6506
+ `schemaVersion` 1, `plan` not a boolean, `deployments` or `rows` not an
6507
+ array, or either longer than 100 000 entries) is a protocol failure,
6508
+ `E_CLI_PROTOCOL`, and is never read in part.
6534
6509
 
6535
6510
  ### Launch configurations
6536
6511
 
@@ -509,6 +509,38 @@ dependencies installed, `check`, `validate`, `pack:check` and the smoke test,
509
509
  and is the gate. Tests use local bare repositories and fakes; none contacts
510
510
  GitHub, aweb, Jira or Linear.
511
511
 
512
+ ### The TUI's tests on macOS
513
+
514
+ A pull request that touches `packages/tui/`, `packages/client/`, a
515
+ `test/tui-*.test.mjs` file or the workflow itself also runs
516
+ [`tui-macos.yml`](../.github/workflows/tui-macos.yml): every TUI test file,
517
+ `packages/tui/test/*.test.mjs` and `test/tui-*.test.mjs`, one file at a time
518
+ and each test within five minutes, on `macos-14` with tmux installed, in about
519
+ five minutes. Its last step fails the run if a test left a tmux server on the
520
+ default `oats` socket, as a hand-started run checks after each file; it does
521
+ not give each file a process group of its own, as a hand-started run does. The
522
+ TUI reads tables keyed by platform (the shared keymap's macOS chords) and
523
+ drives macOS's own tmux, whose output differs from Linux's, and Linux CI sees
524
+ neither ([#1608](https://github.com/awebai/oats/issues/1608),
525
+ [#1613](https://github.com/awebai/oats/issues/1613)). It runs at pull-request
526
+ time, not on the tag's macOS legs: a failure found on the tag costs a version,
527
+ and `release.yml` holds the publishing rights, so a TUI flake there would hold
528
+ a publication (the release lane's call, 2026-10-27).
529
+
530
+ The paths are the TUI's own. A change the TUI depends on outside them (`lib/`,
531
+ `bin/`, `test/helpers/`, `package.json`, `package-lock.json`) starts no run,
532
+ and nothing runs on a push to `main`: such a change wants hand-started macOS
533
+ runs of the TUI's files, at most ten files a run
534
+ ([Named test runs](named-test-runs.md)).
535
+
536
+ The job is not part of the gate above. A path filter that skips the workflow
537
+ reports no check, so a required check would hold every pull request that does
538
+ not touch the TUI. Its run on the pull request is that pull request's macOS
539
+ evidence. `test/tui-macos-workflow.test.mjs` pins its terms: the one trigger
540
+ and its paths, the read-only token, no secret, no artifact or cache, tmux, a
541
+ command that runs every TUI test file, and the leak check. Like the release's
542
+ workflows, it names its actions by commit (`test/workflow-no-cache.test.mjs`).
543
+
512
544
  **Test output is pristine.** A warning that a test expects is captured and
513
545
  asserted by the test, or by its fixture, and never left in the output: a line
514
546
  nobody asserted is then one nobody expected. The root run holds the rule
@@ -1,8 +1,10 @@
1
1
  # Named test runs on macOS and Linux
2
2
 
3
3
  Pull-request CI runs the tests on Linux, in its own way: sharded, and with no
4
- working `systemctl --user`. Some tests need something CI does not give them,
5
- and two workflows run them by hand:
4
+ working `systemctl --user`. Beside it, a pull request that touches the TUI
5
+ also runs the TUI's tests on macOS ([The TUI's tests on
6
+ macOS](implementation.md#the-tuis-tests-on-macos)). Some tests need something
7
+ CI does not give them, and two workflows run them by hand:
6
8
 
7
9
  - **macOS.** Some tests rest on what only macOS does: a file system that
8
10
  ignores case, `/var` and `/tmp` as links, long temporary paths, the BSD
@@ -9,10 +9,10 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.16.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.16.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.5.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.32.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
- | `oats.engineering` | `v1.15.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
15
+ | `oats.engineering` | `v1.17.2` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.5.0`, `5.5.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.5.0` or `oats-framework/v1.16.1`) and the payload path. An id
54
+ convention (`v5.5.0` or `oats-framework/v1.16.2`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.16.1
77
+ oats.framework: v1.16.2
78
78
  oats.okf: v5.5.0
79
79
  oats.aweb: v1.32.0
80
80
  teams:
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.5.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.1", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.2", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.16.1`
362
- resolves to tag `oats-framework/v1.16.1`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.16.2`
362
+ resolves to tag `oats-framework/v1.16.2`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -170,21 +170,26 @@ by a full commit id, with the exact version in a comment beside it:
170
170
 
171
171
  A tag is the action owner's to move, and a commit is not: the code that runs
172
172
  with the publishing rights is the code that was read. `build-installers.yml`
173
- runs the same installer steps, so it names the same commits. Every other
173
+ runs the same installer steps, so it names the same commits. So does
174
+ `tui-macos.yml`, the TUI's tests on macOS at pull-request time, by the release
175
+ lane's call of 2026-10-27: it runs a branch's code on the release's own
176
+ actions, and its run is that pull request's macOS evidence, so it names them
177
+ at the commits that were read
178
+ ([Implementation](implementation.md#the-tuis-tests-on-macos)). Every other
174
179
  workflow keeps tags (`actions/checkout@v4`): nothing is published from them.
175
180
 
176
181
  `test/workflow-no-cache.test.mjs` holds this. Its table of the actions that
177
- were read has a row for each action: `action`, `id`, `version`. In the two files
178
- every `uses:` is a row's id, the same action is the same id in both, and the
179
- comment beside an id is the row's version. In every other workflow a `uses:`
180
- is the major of a row's version.
182
+ were read has a row for each action: `action`, `id`, `version`. In the three
183
+ files every `uses:` is a row's id, the same action is the same id in all of
184
+ them, and the comment beside an id is the row's version. In every other
185
+ workflow a `uses:` is the major of a row's version.
181
186
 
182
187
  **An id is moved by a pull request, reviewed like any change to that
183
- workflow.** It changes these together, and nothing else in the two workflow
188
+ workflow.** It changes these together, and nothing else in the three workflow
184
189
  files:
185
190
 
186
191
  - the id and the version comment, on every `uses:` line of that action in
187
- `release.yml` and `build-installers.yml`;
192
+ `release.yml`, `build-installers.yml` and `tui-macos.yml`;
188
193
  - the action's row in the table.
189
194
 
190
195
  **The id is read from an exact version tag of the action's own repository**
@@ -216,21 +221,23 @@ and packages it depends on, and what its entry points call of a cache.
216
221
  needs `package-manager-cache: false` on every step. The test takes the
217
222
  version of an id from the row, so it refuses a step without it.
218
223
 
219
- **The two files name their runners by version too** (`ubuntu-24.04`, as they
220
- name `macos-14`), never by a label that GitHub moves to another system by
221
- itself (`ubuntu-latest`). The Linux installers are built on that runner, and
222
- what they need of a system follows the system that built them.
224
+ **`release.yml` and `build-installers.yml` name their runners by version
225
+ too** (`ubuntu-24.04`, as they name `macos-14`), never by a label that GitHub
226
+ moves to another system by itself (`ubuntu-latest`). The Linux installers are
227
+ built on that runner, and what they need of a system follows the system that
228
+ built them.
223
229
  `pull-request.yml` keeps `ubuntu-latest` on purpose: when the label moves, a
224
230
  break on the new system shows in pull-request CI first and not at a release.
225
231
 
226
- The labels the two files may name are a list beside the table of actions in
227
- `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and `macos-14`. Every job
228
- of the two files runs on a label of that list, and both files build on the
229
- same Linux. A label is added to the list by whoever decides the runner, as an
230
- action's row is by whoever read it.
232
+ The labels `release.yml` and `build-installers.yml` may name are a list beside
233
+ the table of actions in `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and
234
+ `macos-14`. Every job of the two runs on a label of that list, and both build
235
+ on the same Linux. A label is added to the list by whoever decides the runner,
236
+ as an action's row is by whoever read it.
231
237
 
232
- **Moving the runner is a pull request** that changes the label in the two
233
- files and in the list together, and says what the installers then need.
238
+ **Moving the runner is a pull request** that changes the label in
239
+ `release.yml`, `build-installers.yml` and the list together, and says what the
240
+ installers then need.
234
241
 
235
242
  **What the Linux installer needs today**, to compare with at the next move.
236
243
  Read from `oats-desktop-0.52.0-linux-amd64.deb`, built on `ubuntu-24.04`
@@ -0,0 +1,43 @@
1
+ # OATS 0.69.3
2
+
3
+ Unreleased
4
+
5
+ 0.69.3 fixes `oats tui` killing the host's systemd user manager, and every
6
+ agent with it, when it ended at the wrong moment. It also fixes a terminal
7
+ left open on macOS, and pins oats.engineering 1.16.0.
8
+
9
+ ## Upgrade
10
+
11
+ - **Install the Desktop first and the CLI second,** as
12
+ [Upgrading](../upgrading.md) says. The 0.69.3 Desktop accepts OATS CLIs
13
+ `>=0.26.0 <0.70.0`.
14
+ - **The keeper fix is in the CLI** (`oats tui`). The danger is an `oats tui`
15
+ that ends while its private server is still starting. Until a Linux host
16
+ with systemd has the 0.69.3 CLI, let `oats tui` finish opening before you
17
+ quit it, and don't run it where something may kill it as it starts.
18
+ - **Package moves:** the official catalog pins oats.engineering 1.16.0
19
+ (Provider updates, below). A deployment takes it with `oats sync`.
20
+
21
+ ## Fixed
22
+
23
+ - **`oats tui` can no longer kill your session's systemd user manager.** When `oats tui` ends, a keeper kills its private tmux server. The keeper took its server to be the parent its shell saw when it started. If the server had already ended by then, that parent was `systemd --user` on a systemd host, so an `oats tui` killed at the wrong moment could SIGKILL the user manager and every process under it, every agent of the host included. The keeper now kills only the server that tmux names in the keeper's own `TMUX`, and only while that server is still its parent; in any doubt it kills nothing ([awebai/oats#1615](https://github.com/awebai/oats/issues/1615); [What it reads, and what it runs](../tui.md#what-it-reads-and-what-it-runs)).
24
+
25
+ - **`oats tui` on macOS closes a terminal whose viewer a signal ended.** tmux on macOS names the signal (`kill`, `hup`) where Linux's gives its number, and `oats tui` read only a number or an upper-case name, so on a Mac such a tab could stay open with nothing left in it. It now reads both ([awebai/oats#1613](https://github.com/awebai/oats/issues/1613); [What it reads, and what it runs](../tui.md#what-it-reads-and-what-it-runs)).
26
+
27
+ ## Provider updates
28
+
29
+ - **oats.engineering 1.16.0: who sets the "same work" flag.** The catalog and
30
+ this workspace pin `oats.engineering: v1.16.0`; the floor is unchanged.
31
+ - An expert spawns its developers with `--same-work`
32
+ (`/coordinate-developers`), a developer its reviewer
33
+ (`/run-the-review-loop`), and a lead expert the domain experts it spawns
34
+ as its children for its effort (`/coordinate-experts`).
35
+ - A maintainer launches its leads without it (`/launch-work`): each effort
36
+ is the lead's own. An expert spawned `--relation unrelated` gets no flag.
37
+ - The skills use the flag, and `oats instance same-work`, only on a kernel
38
+ whose `oats version --json` lists `instance-same-work` (OATS 0.69.2 and
39
+ later); on an older one the spawn leaves it out.
40
+ - **Upgrade:** `oats sync` locks it. New spawns get it, and a stopped home
41
+ moves to it with `oats instance upgrade`. On OATS 0.69.2 or later, an expert
42
+ marks a developer it started before with
43
+ `oats instance same-work <developer> on`.
@@ -0,0 +1,73 @@
1
+ # OATS 0.69.4
2
+
3
+ Unreleased
4
+
5
+ 0.69.4 ships the new coordination skills. Finished instances retire
6
+ automatically, coordinated between agents without a human
7
+ (oats.engineering 1.17.2). An overrun maintainer gets an overflow seat. And
8
+ oats.core says a soul's capabilities can call for a spawn (oats.framework
9
+ 1.16.2). There is no kernel or Desktop change beyond the version.
10
+
11
+ ## Upgrade
12
+
13
+ - **Install the Desktop first and the CLI second,** as
14
+ [Upgrading](../upgrading.md) says. The 0.69.4 Desktop accepts OATS CLIs
15
+ `>=0.26.0 <0.70.0`.
16
+ - **Package moves:** the official catalog pins oats.framework 1.16.2 and
17
+ oats.engineering 1.17.2 (Provider updates, below). A deployment takes them
18
+ with `oats sync`.
19
+ - **Running instances keep the skills they were spawned with.** New spawns
20
+ get the new skills. A running instance is stopped first, moved with
21
+ `oats instance upgrade`, then started again (`oats session start`).
22
+
23
+ ## Changed
24
+
25
+ - **oats.core: spawning a child your capabilities call for needs no human.**
26
+ `/oats-operate` and `/oats-souls` said to spawn only when your task or your
27
+ human asks (or a documented workflow requires it), and to ask your human
28
+ when a relation is unclear. They now also admit your soul's capabilities, as
29
+ the "You run on OATS" block already does (a developer spawning its
30
+ reviewer, an expert its developers), and send a question about an unclear
31
+ relation to your parent or the agent that gave you the task, and to your
32
+ human only when no agent can say. A capability that spawns its own helpers
33
+ no longer reads as needing a human for it.
34
+
35
+ ## Provider updates
36
+
37
+ - **oats.engineering 1.17.2: finished instances retire automatically, and an
38
+ overrun maintainer gets an overflow seat.** The catalog and this workspace
39
+ pin `oats.engineering: v1.17.2`. The floor is unchanged.
40
+ - **Automatic retirement** (oats-engineering#28). An instance is finished
41
+ when three things hold:
42
+ - its PRs are merged and green, or closed (handed back is not landed);
43
+ - nothing waits on it;
44
+ - its final harvest is launched.
45
+
46
+ It then sends its parent a done line, and its parent retires it after
47
+ checking that the work tree is clean and pushed and that nothing is
48
+ attached, without asking or telling a human. A developer retires its
49
+ reviewer, an expert its developers, a maintainer the leads it spawned. An
50
+ instance with no OATS parent retires itself. Maintainers are standing
51
+ seats and are never retired this way.
52
+ - **Overflow seat** (oats-engineering#29). A maintainer with more than 5
53
+ efforts of its own in flight spawns one overflow seat as its child. The
54
+ seat drives the new intake up to hand-back. It holds no entry on the lane
55
+ map, and merges, second reads and sign-offs stay with its parent.
56
+ - 1.17.1 and 1.17.2 fix two lines of 1.17.0. An instance with no parent
57
+ retires itself with `oats retire "$OATS_INSTANCE" --self`, because the
58
+ kernel requires the name. The harvest condition names no knowledge-layer
59
+ command: your knowledge layer says whether you have a harvest duty.
60
+ - **Upgrade:** `oats sync` locks it. New spawns get it, and a stopped home
61
+ moves to it with `oats instance upgrade`.
62
+
63
+ - **oats.framework 1.16.2: oats.core 2.9.1.** oats.core's `/oats-operate`
64
+ and `/oats-souls` now state spawning authority the way its "You run on
65
+ OATS" inject already does. You spawn when your task, your human or your
66
+ soul's capabilities say so, so a developer spawning its reviewer, or an
67
+ expert its developers, needs no human. When a relation is unclear, ask
68
+ your parent or the agent that gave you the task first, and your human
69
+ only when no agent can say (#1621). This is text only. The floors are
70
+ unchanged, and the other capabilities are unchanged.
71
+ - **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
72
+ `oats.framework: v1.16.2`. New spawns get it, and a stopped home moves with
73
+ `oats instance upgrade`, from OATS 0.68.0.
@@ -420,8 +420,8 @@ proposes promotions by pull request. See [knowledge](knowledge.md).
420
420
 
421
421
  ### Spawning and coordinating with other agents
422
422
 
423
- OATS agents can run `oats spawn` when their instructions or the
424
- human ask them to create another expert instance. The spawned agent is another
423
+ OATS agents can run `oats spawn` when their task, their human or their
424
+ soul's capabilities call for another instance. The spawned agent is another
425
425
  full OATS instance, with its own soul, home, worktree, and lifecycle.
426
426
 
427
427
  Spawn lineage is **explicit** and relation-based:
package/docs/tui.md CHANGED
@@ -2456,11 +2456,15 @@ with the Desktop (`packages/client/`).
2456
2456
  found on `PATH` like `tmux`.
2457
2457
  - **`mkfifo`** makes `alive`. Without it an open is refused: the line
2458
2458
  says the terminal could not be opened, with what was said under it.
2459
- - **A way to tell that the server is still its parent.** The keeper reads
2460
- that from `/proc` where the system has one (Linux), and otherwise asks
2461
- `ps -o ppid= -p` (macOS). With neither (no `/proc`, and no `ps` or one
2462
- that refuses `-p`, like BusyBox's), the keeper kills nothing. A normal
2463
- end is not affected. An `oats tui` killed with SIGKILL can then leave
2459
+ - **A way to tell that the server is still its parent.** The keeper kills
2460
+ only the server tmux names in the keeper's own `TMUX`, and only while
2461
+ that server is still its parent, read from `/proc` where the system has
2462
+ one (Linux), and otherwise from `ps -o ppid= -p` (macOS). A keeper whose
2463
+ server ended first has been handed to another parent (pid 1, or
2464
+ `systemd --user` on a systemd host), and kills nothing. With no way to
2465
+ read its parent (no `/proc`, and no `ps` or one that refuses `-p`, like
2466
+ BusyBox's), or no server pid in `TMUX`, the keeper kills nothing. A
2467
+ normal end is not affected. An `oats tui` killed with SIGKILL can then leave
2464
2468
  its private server running, with its tabs' viewers still
2465
2469
  attached to their agents, until you end it with `tmux -S
2466
2470
  <run directory>/tmux kill-server`. The next run's sweep leaves that
@@ -2505,7 +2509,9 @@ with the Desktop (`packages/client/`).
2505
2509
  before it has that status (3.4 does, when the viewer's terminal hangs up a
2506
2510
  moment before its process is reaped): `oats tui` then waits for the
2507
2511
  status, which follows at the next report, for ten seconds at most (2.5
2508
- on tmux 3.2, which never says which signal ended a pane). A tmux built
2512
+ on tmux 3.2, which never says which signal ended a pane). tmux says that
2513
+ signal by its number on Linux (`9`) and by the system's name on macOS
2514
+ (`kill`); `oats tui` reads both. A tmux built
2509
2515
  with libutempter can lose a status for good: as it destroys a pane at
2510
2516
  the hang-up, libutempter holds back SIGCHLD while its helper runs, and
2511
2517
  tmux, which reaps only on a SIGCHLD, leaves a viewer that exited in that
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.2** ([release notes](release-notes/v0.69.2.md)).
10
- The 0.69.2 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.4** ([release notes](release-notes/v0.69.4.md)).
10
+ The 0.69.4 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.2,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.4,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.2 first
23
- npm install -g @awebai/oats@0.69.2 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.4 first
23
+ npm install -g @awebai/oats@0.69.4 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.16.1 # bare version → resolves through the official catalog
57
+ oats.framework: v1.16.2 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.5.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "oats.engineering": {
30
30
  "url": "https://github.com/awebai/oats-engineering.git",
31
- "ref": "v1.15.0",
31
+ "ref": "v1.17.2",
32
32
  "path": "oats-package"
33
33
  },
34
34
  "oats.cloning": {
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "oats.framework": {
50
50
  "url": "https://github.com/awebai/oats.git",
51
- "ref": "oats-framework/v1.16.1",
51
+ "ref": "oats-framework/v1.16.2",
52
52
  "path": "oats-package"
53
53
  }
54
54
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.2",
3
+ "version": "0.69.4",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -166,7 +166,7 @@ export function launchFlagIgnored(answer) {
166
166
  * units in total. The first line that does not fit and every line after it are left out, and no line is cut
167
167
  * inside; the first line always fits (a display line is at most MAX_DISPLAY_LINE units). `omitted` counts
168
168
  * the lines left out, 0 when none; an entry with nothing to show was never a line and is not counted. By
169
- * position only, never by words. Shared by launchFlagIgnored and the session-resume reader. */
169
+ * position only, never by words. Used by launchFlagIgnored. */
170
170
  export function boundedWarnings(raw) {
171
171
  const lines = Array.isArray(raw) ? raw.map(w => displayLine(w)).filter(line => line !== null) : [];
172
172
  const warnings = [];
@@ -15,30 +15,24 @@
15
15
  * resumeSupported) runs. Without one nothing runs, nothing is read, the floor does not move and the slot is let go.
16
16
  *
17
17
  * Settled homes keep a home that cannot be resumed from starting a sweep on every read. A sweep `observed()` started
18
- * keeps the lost homes it was started for (its snapshot); when it completes as a sweep (its reading is quiet or a
19
- * notice of an answer that ran: session-resume.mjs sweepCompleted), every one of them is settled, whatever the answer said of it (left out
18
+ * keeps the lost homes it was started for (its snapshot); when it completes as a sweep (its reading is `answered`,
19
+ * of an answer that ran: session-resume.mjs sweepCompleted), every one of them is settled, whatever the answer said of it (left out
20
20
  * because its deployment is not ready, or named busy or unknown), so a home that cannot be resumed costs at most
21
21
  * one observed sweep. Then the answer's rows settle and release homes (session-resume.mjs sweepSettlement: a
22
22
  * refusal, or a home skipped as not lost or not seen running recently, settles it; a session started or running
23
23
  * releases it; anything else changes nothing; the launch sweep has no snapshot, so a busy or unknown home there
24
24
  * stays news for one observed sweep). A later read also releases a local home it shows that lostLocalHomes does not
25
- * name: no longer lost, or running.
25
+ * name: no longer lost, or running. This module reads nothing of the answer itself: its shape is
26
+ * session-resume.mjs's alone.
26
27
  *
27
- * News, not repeats. The kernel reports a refusal again in every sweep: before `read`, the refusals an earlier
28
- * sweep of this trigger reported are left out of a copy of the envelope (session-resume.mjs withoutReported; the
29
- * run's own is never changed). Every other row is this sweep's event and kept. A home released (above) forgets the
30
- * refusals reported for it, so a refusal after it recovered is news again. A host warning (the result's own
31
- * `warnings`, about this computer) is left out the same way once a notice of this trigger showed it: once per run,
32
- * never forgotten (it is no home's); one a quiet sweep carried was never shown, so it stays news. This module reads
33
- * nothing of the answer itself: its shape is session-resume.mjs's alone.
34
- *
35
- * `onReading` gets the reading of every finished sweep, whatever its kind (the caller ignores what it does not
36
- * show). A run that rejects reads as failed, E_CLI_FAILED; a `read` that throws, as failed, E_CLI_PROTOCOL.
28
+ * `read` is given the run's envelope itself, and `onReading` gets the reading of every finished sweep, whatever its
29
+ * kind (the caller ignores what it does not act on). A run that rejects reads as failed, E_CLI_FAILED; a `read`
30
+ * that throws, as failed, E_CLI_PROTOCOL, and settles nothing.
37
31
  *
38
32
  * `dispose()` stops the trigger and never cancels a sweep: a sweep in flight runs on (a kernel change outlives
39
33
  * its client), and its reading is dropped. Nothing here throws out of `launch` or `observed`. */
40
34
  import { resumeSupported, runResumeSweep } from './session-resume-cli.mjs';
41
- import { readResumeSweep, shownHostKeys, sweepCompleted, sweepSettlement, withoutReported } from './session-resume.mjs';
35
+ import { readResumeSweep, sweepCompleted, sweepSettlement } from './session-resume.mjs';
42
36
  import { SESSION_ENDS } from './deployment-data.mjs';
43
37
 
44
38
  export const RESUME_MIN_INTERVAL_MS = 30_000;
@@ -84,35 +78,19 @@ export function lostLocalHomes(rows, localDeploymentIds) {
84
78
  */
85
79
  export function createResumeTrigger({ cli, run = runResumeSweep, read = readResumeSweep, now = Date.now, onReading }) {
86
80
  let launched = null, disposed = false, flying = false, lastStart = null;
87
- const settled = new Set(), reported = new Set(), reportedFor = new Map(); // reportedFor: home → its reported keys
88
- const reportedHost = new Set(); // host warnings a notice showed
81
+ const settled = new Set();
89
82
  let releasedDuring = null; // homes a read released while the sweep in flight ran: newer than its answer
90
83
 
91
- /** A home no longer settled, and the refusals reported for it forgotten. */
84
+ /** A home no longer settled. */
92
85
  function release(home) {
93
86
  releasedDuring?.add(home);
94
87
  settled.delete(home);
95
- for (const key of reportedFor.get(home) ?? []) reported.delete(key);
96
- reportedFor.delete(home);
97
- }
98
-
99
- /** The envelope `read` is given, without the refusals an earlier answer reported and the host warnings a
100
- * notice showed (withoutReported), with this answer's host keys and settlement (sweepSettlement) for after
101
- * the read. Its refusal keys are added at once. */
102
- function digest(envelope) {
103
- const news = { ...withoutReported(envelope, reported, reportedHost), settlement: sweepSettlement(envelope) };
104
- for (const { home, key } of news.keys) {
105
- reported.add(key);
106
- if (!reportedFor.has(home)) reportedFor.set(home, new Set());
107
- reportedFor.get(home).add(key);
108
- }
109
- return news;
110
88
  }
111
89
 
112
90
  /** After the read: a completed sweep settles every home of its snapshot; then the answer's own rows settle and
113
91
  * release (a home it resumed, started, left waiting or found running is released again). A home a read released
114
92
  * while the sweep ran is settled by neither: that read is newer than the sweep's answer. */
115
- function settle(envelope, reading, snapshot, { settlement: { settle: settles, release: released } }, newer) {
93
+ function settle(envelope, reading, snapshot, { settle: settles, release: released }, newer) {
116
94
  const settleIfNotNewer = home => { if (!newer.has(home)) settled.add(home); };
117
95
  if (sweepCompleted(envelope, reading)) for (const home of snapshot) settleIfNotNewer(home);
118
96
  for (const home of settles) settleIfNotNewer(home);
@@ -134,11 +112,11 @@ export function createResumeTrigger({ cli, run = runResumeSweep, read = readResu
134
112
  try {
135
113
  const envelope = await run(probe);
136
114
  try {
137
- const news = digest(envelope);
138
- reading = read(news.envelope);
115
+ // The settlement is taken before the read: a throw from either reads as failed and settles nothing.
116
+ const settlement = sweepSettlement(envelope);
117
+ reading = read(envelope);
139
118
  releasedDuring = null;
140
- settle(envelope, reading, snapshot, news, newer);
141
- for (const key of shownHostKeys(reading, news.hostKeys)) reportedHost.add(key);
119
+ settle(envelope, reading, snapshot, settlement, newer);
142
120
  } catch { reading = { kind: 'failed', code: 'E_CLI_PROTOCOL' }; }
143
121
  } catch { reading = { kind: 'failed', code: 'E_CLI_FAILED' }; }
144
122
  if (!disposed && typeof onReading === 'function') { try { onReading(reading); } catch { /* the caller's */ } }
@@ -1,133 +1,47 @@
1
- /** The machine sweep's answer (`oats session resume --json`, feature `session-resume`), read into a summary of
2
- * facts and put into the clients' words. session-resume-cli.mjs runs it; this module reads what came back.
3
- * Shared by the Desktop and the TUI: pure, no IO, no DOM, never throws on data (only resumeNotice throws, on
4
- * a caller's missing `label`). No sentence names a client's control, so no client terms are needed.
1
+ /** The machine sweep's answer (`oats session resume --json`, feature `session-resume`), read into one of four
2
+ * readings, and the trigger's settlement helpers (session-resume-trigger.mjs). session-resume-cli.mjs runs the
3
+ * sweep; this module reads what came back. Shared by the Desktop and the TUI: pure, no IO, no DOM, never throws
4
+ * on data.
5
5
  *
6
6
  * The answer: `{schemaVersion: 1, plan, deployments: [{deployment, state, swept, reason?, …}], rows:
7
- * [{deployment, instance, outcome, reason?, code?, message?, warnings?, …}], warnings?}`; the result's own
8
- * `warnings` are about the host, not one home. The summary:
9
- * { resumed: [{instance, deployment, warnings, omitted}],
10
- * fresh: [{instance, deployment, reason, warnings, omitted}], reason: FRESH_REASONS or null
11
- * waiting: [{instance, deployment, reason}], a `blocked` row; reason: WAITING_REASONS or null
12
- * refused: [{instance, deployment, reason, code, message}], reason: REFUSED_REASONS or null
13
- * unswept: [{deployment, reason}], not swept; reason: UNSWEPT_REASONS or null
14
- * host: {warnings, omitted}, the result's warnings, bounded as a row's
15
- * omitted, totals: {resumed, fresh, waiting, refused} }
16
- * `refused` carries `reason` beside the four fields the spec lists: the words say when a refusal was this
17
- * boot's, and when the home keeps losing its session. There is no opt-out: an older kernel's `opted-out`
18
- * deployment is unswept with reason null. Nothing is read from the kernel's words: no sentence, warning or
19
- * message is matched. Names, paths, warnings and messages are display lines (display-text.mjs): labels and
20
- * quotes, never used to address anything. A refused `message` is kernel prose, shown only after `OATS says:`,
21
- * never alone with its `code`.
22
- *
23
- * Tolerant per entry: a row or deployment that does not decode (not a record, a name or path that is not a
24
- * string, empty or withheld, an unknown outcome) is dropped alone; an unknown reason under a known outcome is
25
- * null and worded generically; a code not of the kernel's form is null. `already-running` and `skipped` rows
26
- * are counted nowhere and shown nowhere. The answer around them is closed: one that is not the document (no
27
- * schemaVersion 1, `plan` not a boolean, `deployments` or `rows` not an array, or either longer than
7
+ * [{deployment, instance, home, outcome, reason?, code?, message?, warnings?, …}], warnings?}`. Neither client
8
+ * shows anything of it (docs/desktop-instance-start.md, "Nothing is shown"): the reader says only whether it
9
+ * answered, and the trigger reads its rows' homes and outcomes to settle and release homes. Nothing is read from
10
+ * the kernel's words: no sentence, warning or message is matched. The answer is closed: one that is not the
11
+ * document (no schemaVersion 1, `plan` not a boolean, `deployments` or `rows` not an array, or either longer than
28
12
  * RESUME_ANSWER_ENTRIES) is a protocol failure, never read in part. */
29
- import { displayLine, cleanLine, DETAIL_WITHHELD } from './display-text.mjs';
30
- import { boundedWarnings, boundedWarningsValid } from './launch-prompt-outcome.mjs';
31
13
 
32
- /** At most this many rows (over resumed, fresh, waiting and refused, in the answer's order) and, apart, this
33
- * many unswept deployment lines (in the answer's order) are kept. What is left out is counted in `omitted`;
34
- * `totals` keeps the real counts of the rows, which the headline uses. */
35
- export const RESUME_SUMMARY_ROWS = 100;
36
- export const RESUME_SUMMARY_DEPLOYMENTS = 100;
37
- /** The longest `rows` or `deployments` this reader reads: more is a protocol failure, not a summary. */
14
+ /** The longest `rows` or `deployments` this reader reads: more is a protocol failure, not an answer. */
38
15
  export const RESUME_ANSWER_ENTRIES = 100_000;
39
16
  /** A row's `outcome`, by name: the one place a client spells them. */
40
17
  export const RESUME_OUTCOMES = Object.freeze({ resumed: 'resumed', fresh: 'fresh', blocked: 'blocked', refused: 'refused',
41
18
  alreadyRunning: 'already-running', skipped: 'skipped' });
42
- /** A `skipped` row's reasons, by name. A skipped row is counted and shown nowhere, whatever its reason. */
19
+ /** A `skipped` row's reasons, by name. */
43
20
  export const SKIPPED_REASONS = Object.freeze({ notLost: 'not-lost', notSeenRecently: 'not-seen-recently', startBusy: 'start-busy',
44
21
  unknown: 'unknown' });
45
22
  /** The skipped reasons that settle a home (sweepSettlement): it is not lost, or the kernel did not recently see it
46
23
  * running (its status still reads lost, and every sweep would skip it again). */
47
24
  export const SETTLING_SKIPPED_REASONS = Object.freeze([SKIPPED_REASONS.notLost, SKIPPED_REASONS.notSeenRecently]);
48
- export const FRESH_REASONS = Object.freeze(['no-conversation', 'no-receipts', 'resume-unproven']);
49
- export const WAITING_REASONS = Object.freeze(['resume-confirmation', 'launch-prompt']);
50
- export const REFUSED_REASONS = Object.freeze(['start-refused', 'refused-this-boot', 'keeps-getting-lost']);
51
- export const UNSWEPT_REASONS = Object.freeze(['not-ok', 'unreadable']);
52
25
  /** The ok:false codes that mean nothing ran: no compatible CLI, or one without the feature. */
53
26
  const UNSUPPORTED = new Set(['E_CLI_UNAVAILABLE', 'E_RESUME_FEATURE']);
54
27
  const CODE = /^E_[A-Z0-9_]{1,64}$/;
55
- const KINDS = ['resumed', 'fresh', 'waiting', 'refused'];
56
- const SUMMARY_KEYS = [...KINDS, 'unswept', 'host', 'omitted', 'totals'];
57
28
 
58
29
  const record = v => v !== null && typeof v === 'object' && !Array.isArray(v);
59
- const exactKeys = (v, keys) => record(v) && Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
60
- const known = (list, v) => list.includes(v) ? v : null;
61
30
  const code = v => typeof v === 'string' && CODE.test(v) ? v : null;
62
- /** A name or a path as a label: one display line, null when it is withheld or there is nothing to show. */
63
- const label = v => { const line = displayLine(v); return line === DETAIL_WITHHELD ? null : line; };
64
- const named = v => cleanLine(v) && v !== DETAIL_WITHHELD;
65
- const count = v => Number.isSafeInteger(v) && v >= 0;
66
- const sum = totals => KINDS.reduce((n, k) => n + totals[k], 0);
67
-
68
- /** One counted row as its kind and fact, or null (dropped, or counted nowhere). */
69
- function decodeRow(row) {
70
- if (!record(row)) return null;
71
- const instance = label(row.instance), deployment = label(row.deployment);
72
- if (instance === null || deployment === null) return null;
73
- switch (row.outcome) {
74
- case RESUME_OUTCOMES.resumed: return ['resumed', { instance, deployment, ...boundedWarnings(row.warnings) }];
75
- case RESUME_OUTCOMES.fresh: return ['fresh', { instance, deployment, reason: known(FRESH_REASONS, row.reason), ...boundedWarnings(row.warnings) }];
76
- case RESUME_OUTCOMES.blocked: return ['waiting', { instance, deployment, reason: known(WAITING_REASONS, row.reason) }];
77
- case RESUME_OUTCOMES.refused: return ['refused', { instance, deployment, reason: known(REFUSED_REASONS, row.reason), code: code(row.code), message: displayLine(row.message) }];
78
- default: return null;
79
- }
80
- }
81
31
 
82
- /** One unswept deployment line, `{deployment, reason}`, or null (swept, or dropped). */
83
- function decodeDeployment(d) {
84
- if (!record(d)) return null;
85
- const deployment = label(d.deployment);
86
- if (deployment === null) return null;
87
- return d.swept === true ? null : { deployment, reason: known(UNSWEPT_REASONS, d.reason) };
88
- }
89
-
90
- const empty = () => ({ resumed: [], fresh: [], waiting: [], refused: [], unswept: [], host: { warnings: [], omitted: 0 }, omitted: 0,
91
- totals: { resumed: 0, fresh: 0, waiting: 0, refused: 0 } });
92
-
93
- /** Whether `result` is the sweep's document: the one check the summary and the trigger's helpers share. */
32
+ /** Whether `result` is the sweep's document: the one check the reader and the trigger's helpers share. */
94
33
  const sweepDocument = result => record(result) && result.schemaVersion === 1 && typeof result.plan === 'boolean'
95
34
  && Array.isArray(result.deployments) && Array.isArray(result.rows)
96
35
  && result.deployments.length <= RESUME_ANSWER_ENTRIES && result.rows.length <= RESUME_ANSWER_ENTRIES;
97
36
 
98
- /** The sweep's `result` as a summary, or null when it is not the document. A plan (`plan: true`) started
99
- * nothing, so it is the empty summary: none of its rows, deployments or warnings is read. The result's own
100
- * `warnings` (about the host) are kept as a row's are (boundedWarnings): a host warning alone is no row, so
101
- * it never makes a notice. */
102
- function summarize(result) {
103
- if (!sweepDocument(result)) return null;
104
- const s = empty();
105
- if (result.plan) return s;
106
- let rows = 0, lines = 0;
107
- for (const row of result.rows) {
108
- const decoded = decodeRow(row);
109
- if (!decoded) continue;
110
- const [kind, fact] = decoded;
111
- s.totals[kind] += 1;
112
- if (rows < RESUME_SUMMARY_ROWS) { s[kind].push(fact); rows += 1; } else s.omitted += 1;
113
- }
114
- for (const d of result.deployments) {
115
- const decoded = decodeDeployment(d);
116
- if (!decoded) continue;
117
- if (lines < RESUME_SUMMARY_DEPLOYMENTS) { s.unswept.push(decoded); lines += 1; } else s.omitted += 1;
118
- }
119
- s.host = boundedWarnings(result.warnings);
120
- return s;
121
- }
122
-
123
37
  /**
124
38
  * @param {unknown} envelope what runResumeSweep resolved: the kernel's envelope or a client read error
125
- * @returns {{kind: 'unsupported'} | {kind: 'busy'} | {kind: 'failed', code: string}
126
- * | {kind: 'quiet', summary} | {kind: 'notice', summary}}
39
+ * @returns {{kind: 'unsupported'} | {kind: 'busy'} | {kind: 'failed', code: string} | {kind: 'answered'}}
127
40
  * `unsupported`: nothing ran (no compatible CLI, or no feature). `busy`: another sweep holds the machine's
128
41
  * lock and nothing started. `failed`: any other refusal, with its code when it has the kernel's form, else
129
- * E_CLI_PROTOCOL, as is an answer that does not decode. `notice` when a row was resumed, fresh, blocked
130
- * or refused; `quiet` otherwise, also when only unswept deployments are left to say.
42
+ * E_CLI_PROTOCOL, as is an `ok: true` answer whose result is not the sweep's document (sweepDocument).
43
+ * `answered`: an `ok: true` answer whose result is the document, a plan too (a plan completes nothing:
44
+ * sweepCompleted). No reading carries anything of the answer's rows or words.
131
45
  */
132
46
  export function readResumeSweep(envelope) {
133
47
  if (record(envelope) && envelope.ok === false) {
@@ -136,14 +50,13 @@ export function readResumeSweep(envelope) {
136
50
  if (c === 'E_RESUME_BUSY') return { kind: 'busy' };
137
51
  return { kind: 'failed', code: code(c) ?? 'E_CLI_PROTOCOL' };
138
52
  }
139
- const summary = record(envelope) && envelope.ok === true ? summarize(envelope.result) : null;
140
- if (!summary) return { kind: 'failed', code: 'E_CLI_PROTOCOL' };
141
- return { kind: sum(summary.totals) > 0 ? 'notice' : 'quiet', summary };
53
+ if (record(envelope) && envelope.ok === true && sweepDocument(envelope.result)) return { kind: 'answered' };
54
+ return { kind: 'failed', code: 'E_CLI_PROTOCOL' };
142
55
  }
143
56
 
144
57
  /** The rows of an answer the trigger reads (session-resume-trigger.mjs): the rows of an `ok: true` envelope
145
58
  * whose result is the sweep's document (sweepDocument, as readResumeSweep reads it) and not a plan, else null:
146
- * an answer the reader fails or reads as nothing settles nothing and leaves nothing out. */
59
+ * an answer the reader fails, or a plan, settles nothing. */
147
60
  function answerRows(envelope) {
148
61
  const result = record(envelope) && envelope.ok === true ? envelope.result : undefined;
149
62
  return sweepDocument(result) && result.plan === false ? result.rows : null;
@@ -153,8 +66,6 @@ const homeOf = row => record(row) && typeof row.home === 'string' && row.home !=
153
66
  const settles = row => row.outcome === RESUME_OUTCOMES.refused
154
67
  || row.outcome === RESUME_OUTCOMES.skipped && SETTLING_SKIPPED_REASONS.includes(row.reason);
155
68
  const RELEASES = new Set([RESUME_OUTCOMES.resumed, RESUME_OUTCOMES.fresh, RESUME_OUTCOMES.blocked, RESUME_OUTCOMES.alreadyRunning]);
156
- /** A refused row's (home, reason, code), as one string; the format is this module's alone. */
157
- const reportedKey = (home, row) => JSON.stringify([home, row.reason ?? null, row.code ?? null]);
158
69
 
159
70
  /**
160
71
  * The homes a sweep's answer settles and releases, for the trigger's settled homes. A row `refused` (any
@@ -177,156 +88,8 @@ export function sweepSettlement(envelope) {
177
88
  return { settle, release };
178
89
  }
179
90
 
180
- /**
181
- * News, not repeats: the answer without what an earlier answer already reported, and this answer's keys.
182
- * `envelope` is a copy (the given one is never changed) that leaves out each `refused` row with a string home
183
- * whose (home, reason, code) key is in `reported`, and each host warning (the result's `warnings`) whose
184
- * exact string is in `reportedHost`; everything else is kept, in order (`warnings` absent when none is left).
185
- * `keys` are the keys of every such refused row of this answer, those left out too, each with its home, for
186
- * the caller to add to `reported` after (and to forget by home). `hostKeys` are the host warnings kept, each
187
- * that becomes a line, in order: shownHostKeys says which of them a reading showed. Keys are opaque outside
188
- * this module. An envelope that is not the sweep's document (answerRows) is given back as it came, with no keys.
189
- * @param {unknown} envelope
190
- * @param {Set<string>} reported refusal keys an earlier answer gave
191
- * @param {Set<string>} [reportedHost] host keys an earlier notice showed
192
- * @returns {{envelope: unknown, keys: {home: string, key: string}[], hostKeys: string[]}}
193
- */
194
- export function withoutReported(envelope, reported, reportedHost = new Set()) {
195
- const rows = answerRows(envelope);
196
- if (!rows) return { envelope, keys: [], hostKeys: [] };
197
- const keys = [];
198
- const kept = rows.filter(row => {
199
- const home = homeOf(row);
200
- if (home === null || row.outcome !== RESUME_OUTCOMES.refused) return true;
201
- const key = reportedKey(home, row);
202
- keys.push({ home, key });
203
- return !reported.has(key);
204
- });
205
- // Host warnings: a reported one left out by its exact string; a `warnings` that is not an array passes as it is.
206
- const { warnings: given, ...result } = envelope.result;
207
- if (!Array.isArray(given)) return { envelope: { ...envelope, result: { ...envelope.result, rows: kept } }, keys, hostKeys: [] };
208
- const host = given.filter(w => typeof w !== 'string' || !reportedHost.has(w));
209
- const hostKeys = host.filter(w => typeof w === 'string' && displayLine(w) !== null);
210
- return { envelope: { ...envelope, result: { ...result, rows: kept, ...(host.length ? { warnings: host } : {}) } }, keys, hostKeys };
211
- }
212
-
213
91
  /** Whether a sweep completed: its answer is the sweep's document and not a plan (answerRows: it ran), and its
214
- * reading is `quiet` or `notice`. Busy, failed, unsupported and a plan are not: nothing can be concluded about a
215
- * home from them. `envelope` is the run's answer, `reading` what was read of it. */
92
+ * reading is `answered`. Busy, failed, unsupported and a plan are not: nothing can be concluded about a home from
93
+ * them. `envelope` is the run's answer, `reading` what was read of it. */
216
94
  export const sweepCompleted = (envelope, reading) => answerRows(envelope) !== null
217
- && record(reading) && (reading.kind === 'quiet' || reading.kind === 'notice');
218
-
219
- /** The host keys of `hostKeys` (withoutReported's, for the envelope `reading` was read from) that the reading
220
- * showed: none unless it is a notice, else those its summary kept, in order (the cut is by position). A host
221
- * warning a quiet sweep carried was never shown, so it stays news. */
222
- export function shownHostKeys(reading, hostKeys) {
223
- if (!record(reading) || reading.kind !== 'notice' || !record(reading.summary) || !record(reading.summary.host)
224
- || !Array.isArray(reading.summary.host.warnings) || !Array.isArray(hostKeys)) return [];
225
- return hostKeys.slice(0, reading.summary.host.warnings.length);
226
- }
227
-
228
- /** Whether each kept fact has its kind's exact shape. */
229
- const rowShape = {
230
- resumed: r => exactKeys(r, ['instance', 'deployment', 'warnings', 'omitted']) && boundedWarningsValid(r.warnings, r.omitted),
231
- fresh: r => exactKeys(r, ['instance', 'deployment', 'reason', 'warnings', 'omitted']) && (r.reason === null || FRESH_REASONS.includes(r.reason))
232
- && boundedWarningsValid(r.warnings, r.omitted),
233
- waiting: r => exactKeys(r, ['instance', 'deployment', 'reason']) && (r.reason === null || WAITING_REASONS.includes(r.reason)),
234
- refused: r => exactKeys(r, ['instance', 'deployment', 'reason', 'code', 'message']) && (r.reason === null || REFUSED_REASONS.includes(r.reason))
235
- && (r.code === null || code(r.code) !== null) && (r.message === null || cleanLine(r.message)),
236
- };
237
- const copyRow = r => Object.hasOwn(r, 'warnings') ? { ...r, warnings: [...r.warnings] } : { ...r };
238
-
239
- /** The summary as given to resumeNotice, decoded again at that boundary: the same summary, a fresh copy, or
240
- * undefined. Exactly the keys above, everywhere; names and paths display lines, never withheld or empty;
241
- * reasons one of their kind's or null; codes of the kernel's form or null; each row's warnings within both
242
- * bounds with `omitted` consistent (boundedWarningsValid); at most RESUME_SUMMARY_ROWS rows and
243
- * RESUME_SUMMARY_DEPLOYMENTS deployment lines; `host` the host warnings within both bounds (boundedWarningsValid);
244
- * `totals` non-negative safe integers, each at least its kind's
245
- * kept rows. `omitted` is the rows over the bound (the totals' sum less the kept rows: above 0 only beside
246
- * a full set of rows) plus the deployment lines over theirs (above 0 only beside a full set of lines).
247
- * Idempotent: readResumeSweep's summary decodes to itself, and so does this function's answer. */
248
- export function resumeSummaryFact(v) {
249
- if (!exactKeys(v, SUMMARY_KEYS) || !exactKeys(v.totals, KINDS) || !KINDS.every(k => count(v.totals[k]))
250
- || !count(v.omitted) || !Array.isArray(v.unswept)
251
- || !exactKeys(v.host, ['warnings', 'omitted']) || !boundedWarningsValid(v.host.warnings, v.host.omitted)) return undefined;
252
- let kept = 0;
253
- for (const k of KINDS) {
254
- const rows = v[k];
255
- if (!Array.isArray(rows) || rows.length > v.totals[k]
256
- || !rows.every(r => rowShape[k](r) && named(r.instance) && named(r.deployment))) return undefined;
257
- kept += rows.length;
258
- }
259
- const lines = v.unswept.length, total = sum(v.totals);
260
- if (kept > RESUME_SUMMARY_ROWS || lines > RESUME_SUMMARY_DEPLOYMENTS || !Number.isSafeInteger(total)
261
- || !v.unswept.every(u => exactKeys(u, ['deployment', 'reason']) && named(u.deployment) && (u.reason === null || UNSWEPT_REASONS.includes(u.reason)))) return undefined;
262
- const overRows = total - kept, overLines = v.omitted - overRows;
263
- if (overRows > 0 && kept < RESUME_SUMMARY_ROWS || overLines < 0 || overLines > 0 && lines < RESUME_SUMMARY_DEPLOYMENTS) return undefined;
264
- const out = {};
265
- for (const k of KINDS) out[k] = v[k].map(copyRow);
266
- return { ...out, unswept: v.unswept.map(u => ({ ...u })), host: { warnings: [...v.host.warnings], omitted: v.host.omitted },
267
- omitted: v.omitted, totals: { ...v.totals } };
268
- }
269
-
270
- const FRESH_WHY = {
271
- 'no-conversation': 'no saved conversation was found.',
272
- 'no-receipts': 'OATS has no record of where its conversations are kept.',
273
- 'resume-unproven': "resuming this harness's conversations isn't supported yet.",
274
- };
275
- const UNSWEPT_WHY = { 'not-ok': "its deployment isn't ready.", unreadable: 'it could not be read.' };
276
- const THIS_BOOT = ' It was refused earlier since this computer started, so OATS did not try again.';
277
- const KEEPS_LOST = "keeps losing its session, so OATS stopped resuming it: start it yourself once it's fixed.";
278
- /** A refused row's line: `keeps-getting-lost` says why in place of "could not be resumed.". */
279
- const refusedLine = r => r.reason === 'keeps-getting-lost' ? KEEPS_LOST
280
- : `could not be resumed.${r.reason === 'refused-this-boot' ? THIS_BOOT : ''}`;
281
-
282
- /** The headline's sentences, each only when its count is above 0. A blocked row's session runs, so it counts
283
- * among the resumed: N = resumed + fresh + waiting. "1 of them" takes "its"; "It" when the one is all of N. */
284
- function headline({ resumed, fresh: f, waiting: w, refused: r }) {
285
- const n = resumed + f + w, out = [];
286
- if (n > 0) out.push(n === 1 ? 'OATS resumed 1 instance whose session was lost.' : `OATS resumed ${n} instances whose sessions were lost.`);
287
- if (f > 0) out.push(f === n && n === 1 ? 'It started fresh from its briefing.'
288
- : f === 1 ? '1 of them started fresh from its briefing.' : `${f} of them started fresh from their briefing.`);
289
- if (w > 0) out.push(w === n && n === 1 ? 'It is waiting for you: open its terminal.'
290
- : w === 1 ? '1 of them is waiting for you: open its terminal.' : `${w} of them are waiting for you: open their terminals.`);
291
- if (r > 0) out.push(n > 0 ? `${r} could not be resumed.` : r === 1 ? 'OATS could not resume 1 lost session.' : `OATS could not resume ${r} lost sessions.`);
292
- return out.join(' ');
293
- }
294
-
295
- /** A row's warnings under `OATS says:`, in order, then how many more the cut left out; nothing without one. */
296
- const said = r => r.warnings.length ? ['OATS says:', ...r.warnings, ...(r.omitted > 0 ? [`${r.omitted} more not shown.`] : [])] : [];
297
-
298
- /**
299
- * The notice for a summary in the clients' words: `{headline, detail}`, or null when `summary` does not
300
- * decode (resumeSummaryFact) or has no row to tell of. Kernel text appears only after `OATS says:`.
301
- * @param {unknown} summary
302
- * @param {{label: (deployment: string) => string}} options `label` is the caller's display label for a
303
- * deployment path (required: a TypeError without it); a non-string or empty label shows the path itself.
304
- * Detail: a line per kept row, waiting, refused, fresh, resumed; then the unswept deployments; then the host
305
- * warnings under `OATS says about this computer:` (and how many more the cut left out); then
306
- * `M more not shown.` when anything was left out. A row line names its deployment (` in {d}`) only when the
307
- * kept rows name more than one; a deployment line always does. A refused row's kernel message follows it on
308
- * its own line, as `OATS says: …`. `detail` is the lines joined with '\n', absent when there are none.
309
- */
310
- export function resumeNotice(summary, options) {
311
- const labelOf = options?.label;
312
- if (typeof labelOf !== 'function') throw new TypeError('resumeNotice needs a label function');
313
- const s = resumeSummaryFact(summary);
314
- if (!s || sum(s.totals) === 0) return null;
315
- const shown = d => { const l = labelOf(d); return typeof l === 'string' && l ? l : d; };
316
- const several = new Set(KINDS.flatMap(k => s[k].map(r => r.deployment))).size > 1;
317
- const who = r => several ? `${r.instance} in ${shown(r.deployment)}` : r.instance;
318
- const lines = [
319
- ...s.waiting.map(r => r.reason === 'resume-confirmation'
320
- ? `${who(r)}: waiting for you to choose how to resume it. Open its terminal.`
321
- : `${who(r)}: waiting at a launch prompt. Open its terminal.`),
322
- ...s.refused.flatMap(r => [`${who(r)}: ${refusedLine(r)}`,
323
- ...(r.message !== null ? [`OATS says: ${r.message}`] : [])]),
324
- ...s.fresh.flatMap(r => [`${who(r)}: started fresh from its briefing, ${FRESH_WHY[r.reason] ?? 'its conversation could not be resumed.'}`, ...said(r)]),
325
- ...s.resumed.flatMap(r => [`${who(r)}: resumed in its own conversation.`, ...said(r)]),
326
- ...s.unswept.map(u => `Not checked in ${shown(u.deployment)}: ${UNSWEPT_WHY[u.reason] ?? 'it could not be checked.'}`),
327
- ...(s.host.warnings.length ? ['OATS says about this computer:', ...s.host.warnings,
328
- ...(s.host.omitted > 0 ? [`${s.host.omitted} more not shown.`] : [])] : []),
329
- ...(s.omitted > 0 ? [`${s.omitted} more not shown.`] : []),
330
- ];
331
- return lines.length ? { headline: headline(s.totals), detail: lines.join('\n') } : { headline: headline(s.totals) };
332
- }
95
+ && record(reading) && reading.kind === 'answered';
@@ -190,10 +190,13 @@ export const FRAME_MS = 16;
190
190
  export const VIEW_SCRIPT = 'exec "$0" "$@" 2>"$E"';
191
191
  /** The control client's subscription to every pane's end (THE END OF A VIEWER): its name, and
192
192
  * the line tmux prints when a pane's value changes, `1 <status> ` for a dead pane whose process
193
- * exited, `1 <signal>` for one a signal ended (a name, or its number), `1 ` for one whose status
194
- * tmux does not have yet (or, on tmux 3.2, a signal's), `0 ` for a live one. */
193
+ * exited, `1 <signal>` for one a signal ended, `1 ` for one whose status tmux does not have yet
194
+ * (or, on tmux 3.2, a signal's), `0 ` for a live one. The signal is as tmux's sig2name says it:
195
+ * the libc's own name where it has `sys_signame`, as macOS's does (`kill`, `hup`), and its number
196
+ * elsewhere, as on Linux (`9`); on macOS a viewer a signal ended was never over while only upper
197
+ * case was read (awebai/oats#1613). A status and a signal together is no line of tmux's. */
195
198
  const DEAD_SUBSCRIPTION = "oats-tui-dead";
196
- const DEAD_LINE = /^%subscription-changed oats-tui-dead \$\d+ (@\d+) \d+ %\d+ : ([01]) (\d{0,3}) ([A-Z0-9]{0,12})$/;
199
+ const DEAD_LINE = /^%subscription-changed oats-tui-dead \$\d+ (@\d+) \d+ %\d+ : ([01]) (?:(\d{1,3}) | ([A-Za-z0-9]{1,12})| )$/;
197
200
  /** On tmux 3.2 (no `pane_dead_signal`), how long a viewer heard dead with no status and no signal
198
201
  * (`1 `) waits for the line that has one, in milliseconds: two checks of the subscription past
199
202
  * the one that heard it. */
@@ -220,15 +223,22 @@ export const SESSION = "oats-tui";
220
223
  * the TUI is already gone). Then the keeper SIGKILLs its parent, the server: `kill-server` or
221
224
  * SIGTERM would not do, since a server ends only once its clients are gone, and the client tmux
222
225
  * cannot drain is never gone. The kernel then closes every pane's terminal, so each viewer gets
223
- * SIGHUP and cleans up, and the control client, its server gone, exits. The parent is killed only
224
- * while it is still the keeper's parent: a keeper whose server has ended is reparented, and its
225
- * `$PPID` may name another process by then. The parent now is read from `/proc/$$/stat` where
226
- * there is one (field 4, after the `) ` that ends the command name, which may itself hold one),
227
- * else from `ps -o ppid= -p $$` (macOS). FAIL SAFE: when neither names it (no /proc, and no ps or
228
- * one that refuses `-p`, as BusyBox's does), nothing is killed, and the server is left to the
229
- * stdin EOF alone (docs/tui.md says what that can leave). `read` and `kill` are the shell's own:
230
- * a PATH without them does not matter. All of it quietly. */
231
- export const KEEPER_SCRIPT = 'exec 3<>"$1" 4<"$1" 3>&-; cat <&4 >/dev/null; exec >/dev/null 2>&1; p=; if [ -r /proc/$$/stat ]; then read -r s </proc/$$/stat; set -- ${s##*) }; p=$2; else set -- $(ps -o ppid= -p $$); p=$1; fi; [ -n "$p" ] && [ "$p" -eq "$PPID" ] && kill -KILL "$PPID"';
226
+ * SIGHUP and cleans up, and the control client, its server gone, exits.
227
+ * WHICH PROCESS IS THE SERVER. Never `$PPID`: the shell reads it once, as it starts, and a keeper
228
+ * whose server ended before its shell started has already been reparented, to pid 1 or to the
229
+ * nearest subreaper, which on a systemd host is the user's `systemd --user`. That pid was then
230
+ * both `$PPID` and the parent now, and the keeper SIGKILLed the user manager and every process
231
+ * under it (awebai/oats#1615). The server's pid is the one tmux itself puts in every pane's
232
+ * environment, `TMUX=<socket>,<server pid>,<session>`, read from the right (a socket's path may
233
+ * hold a comma). The server is killed only while it is the keeper's parent now, read from
234
+ * `/proc/$$/stat` where there is one (field 4, after the `) ` that ends the command name, which
235
+ * may itself hold one), else from `ps -o ppid= -p $$` (macOS): a keeper whose server has ended
236
+ * has another parent, and kills nothing. FAIL SAFE: nothing is killed when `TMUX` names no pid
237
+ * above 1, or the parent now cannot be read (no /proc, and no ps or one that refuses `-p`, as
238
+ * BusyBox's does), or is not that pid; the server is then left to the stdin EOF alone
239
+ * (docs/tui.md says what that can leave). `read` and `kill` are the shell's own: a PATH without
240
+ * them does not matter. All of it quietly. */
241
+ export const KEEPER_SCRIPT = 'exec 3<>"$1" 4<"$1" 3>&-; cat <&4 >/dev/null; exec >/dev/null 2>&1; t=${TMUX%,*}; t=${t##*,}; case $t in ""|*[!0-9]*) exit 0;; esac; [ "$t" -gt 1 ] || exit 0; p=; if [ -r /proc/$$/stat ]; then read -r s </proc/$$/stat; set -- ${s##*) }; p=$2; else set -- $(ps -o ppid= -p $$); p=$1; fi; case $p in ""|*[!0-9]*) exit 0;; esac; [ "$p" -eq "$t" ] && kill -KILL "$t"';
232
242
  /** The command list the control client starts the server with (see THE START above): the session
233
243
  * with its keeper, attached; `exit-unattached` at once after it; then every option. `unbind-key
234
244
  * -a` empties the prefix table only: the root table (mouse bindings by default) and the
@@ -597,7 +607,7 @@ export function createPanel({ dir, capture, onScreen = () => {}, onActivity = ()
597
607
  else if (kind === "%subscription-changed") {
598
608
  const dead = DEAD_LINE.exec(line);
599
609
  if (first === DEAD_SUBSCRIPTION) traced(dead ? line : `${DEAD_SUBSCRIPTION}: a line not of its shape`);
600
- if (dead && dead[2] === "1") paneDied(dead[1], dead[3] !== "" ? Number(dead[3]) : dead[4] !== "" ? null : PENDING);
610
+ if (dead && dead[2] === "1") paneDied(dead[1], dead[3] !== undefined ? Number(dead[3]) : dead[4] !== undefined ? null : PENDING);
601
611
  }
602
612
  }
603
613
 
@@ -726,13 +726,13 @@ function listedHeard(state, { rows, failure }) {
726
726
  return { state: next(state, { listed: Object.freeze({ rows: Object.freeze(rows.map((row) => Object.freeze({ path: row.path, name: row.name, state: row.state }))), failure: null }) }), effect: null };
727
727
  }
728
728
 
729
- /** The kernel's machine sweep read (lib/main.mjs; the shared readResumeSweep's `{ kind, summary?, code? }`).
729
+ /** The kernel's machine sweep read (lib/main.mjs; the shared readResumeSweep's `{ kind, code? }`).
730
730
  * The TUI says nothing of a sweep (docs/tui.md, "Resuming lost sessions"): no line, whatever it read,
731
- * and the list shows each instance as it is after the next read. A sweep that ran (`notice`, `quiet`)
731
+ * and the list shows each instance as it is after the next read. A sweep that answered (`answered`)
732
732
  * asks for that read live, so a resumed row reads running; one that failed, found the machine's sweep
733
733
  * busy, or a kernel without it, asks for nothing. */
734
734
  function resumedHeard(state, reading) {
735
- if (reading?.kind === "notice" || reading?.kind === "quiet") return { state, effect: { refresh: { live: true } } };
735
+ if (reading?.kind === "answered") return { state, effect: { refresh: { live: true } } };
736
736
  return { state, effect: null };
737
737
  }
738
738
 
@@ -350,7 +350,7 @@ name: acme
350
350
  members:
351
351
  - git:github.com/acme/acme-oats # the host is a member too
352
352
  packages:
353
- oats.framework: v1.16.1 # the installed CLI's catalog versions (below)
353
+ oats.framework: v1.16.2 # the installed CLI's catalog versions (below)
354
354
  oats.aweb: v1.32.0 # messaging, and tasks: agent identities, mail, chat and tasks
355
355
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
356
356
  defaults:
@@ -365,7 +365,7 @@ defaultTeam: acme # every soul starts in this team
365
365
 
366
366
  - **The versions** are the installed CLI's catalog's:
367
367
  `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
368
- (for example `oats-framework/v1.16.1`: write the part after the `/`) and
368
+ (for example `oats-framework/v1.16.2`: write the part after the `/`) and
369
369
  `packages."oats.aweb".ref`, but never below `v1.31.0`: that release
370
370
  carries `oats.aweb-tasks`, and a bare version resolves through the
371
371
  catalog's tag convention even when the installed catalog names an older