@awebai/oats 0.50.0 → 0.52.0

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 (132) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +153 -51
  3. package/docs/capabilities.md +11 -3
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +994 -71
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +230 -59
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +73 -8
  12. package/docs/integrations.md +9 -8
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +43 -7
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.51.0.md +156 -0
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/schedules.md +91 -4
  27. package/docs/servers.md +21 -2
  28. package/docs/souls-and-instances.md +113 -21
  29. package/docs/tui.md +152 -0
  30. package/docs/workspaces.md +2 -2
  31. package/lib/claim.mjs +266 -0
  32. package/lib/core.mjs +845 -166
  33. package/lib/errors.mjs +170 -0
  34. package/lib/harness-trust-write.mjs +68 -27
  35. package/lib/harness-trust.mjs +34 -16
  36. package/lib/instance-inspect.mjs +40 -11
  37. package/lib/instance-lifecycle.mjs +169 -47
  38. package/lib/launch-preference.mjs +16 -0
  39. package/lib/launch-prompt-completion.mjs +7 -43
  40. package/lib/launch-prompt-evidence.mjs +14 -7
  41. package/lib/launch-prompt-fixtures/README.md +86 -152
  42. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  43. package/lib/launch-prompt-fixtures.mjs +122 -109
  44. package/lib/launch-prompt-transport.mjs +2 -56
  45. package/lib/launch-prompts.mjs +102 -100
  46. package/lib/schedule-host.mjs +154 -22
  47. package/lib/schedule.mjs +73 -24
  48. package/lib/servers.mjs +20 -4
  49. package/lib/session-viewer.mjs +87 -10
  50. package/lib/system-tools.mjs +39 -0
  51. package/lib/tmux-server-scope.mjs +62 -0
  52. package/lib/triggers.mjs +4 -4
  53. package/lib/workspace.mjs +5 -11
  54. package/lib/worktree-hooks.mjs +116 -23
  55. package/lib/worktree.mjs +89 -102
  56. package/package-catalog.json +3 -3
  57. package/package.json +7 -2
  58. package/packages/client/capability-show-contract.mjs +230 -0
  59. package/packages/client/capability-warnings-contract.mjs +57 -0
  60. package/packages/client/cli-adapter.mjs +548 -0
  61. package/packages/client/cli-environment.mjs +53 -0
  62. package/packages/client/cli-locator.mjs +253 -0
  63. package/packages/client/cli-probe-contract.mjs +47 -0
  64. package/packages/client/client-terms.mjs +60 -0
  65. package/packages/client/deployment-contract.mjs +68 -0
  66. package/packages/client/deployment-data.mjs +483 -0
  67. package/packages/client/deployment-facts.mjs +34 -0
  68. package/packages/client/deployment-label.mjs +76 -0
  69. package/packages/client/deployment-observer.mjs +89 -0
  70. package/packages/client/deployment-panel.mjs +142 -0
  71. package/packages/client/deployment-read-cli.mjs +53 -0
  72. package/packages/client/display-text.mjs +44 -0
  73. package/packages/client/harness-names.mjs +30 -0
  74. package/packages/client/inspect-contract.mjs +62 -0
  75. package/packages/client/instance-acts.mjs +54 -0
  76. package/packages/client/instance-admission.mjs +45 -0
  77. package/packages/client/instance-events-contract.mjs +74 -0
  78. package/packages/client/instance-git-contract.mjs +80 -0
  79. package/packages/client/instance-presentation.mjs +22 -0
  80. package/packages/client/instance-tree.mjs +453 -0
  81. package/packages/client/kernel-environment.mjs +11 -0
  82. package/packages/client/launch-contract.mjs +51 -0
  83. package/packages/client/launch-prompt-outcome.mjs +165 -0
  84. package/packages/client/lifecycle-cli.mjs +61 -0
  85. package/packages/client/lifecycle-contract.mjs +372 -0
  86. package/packages/client/liveness-main.mjs +10 -0
  87. package/packages/client/liveness.mjs +35 -0
  88. package/packages/client/machine-contract.mjs +123 -0
  89. package/packages/client/own-environment.mjs +22 -0
  90. package/packages/client/panel-views.mjs +286 -0
  91. package/packages/client/readiness-contract.mjs +172 -0
  92. package/packages/client/refresh-loop.mjs +52 -0
  93. package/packages/client/remote-address.mjs +126 -0
  94. package/packages/client/remote-roster.mjs +67 -0
  95. package/packages/client/roster-sections.mjs +80 -0
  96. package/packages/client/spawn-apply-cli.mjs +104 -0
  97. package/packages/client/spawn-apply-contract.mjs +183 -0
  98. package/packages/client/spawn-decision.mjs +46 -0
  99. package/packages/client/spawn-messages.mjs +119 -0
  100. package/packages/client/spawn-preview-cli.mjs +32 -0
  101. package/packages/client/spawn-preview-contract.mjs +314 -0
  102. package/packages/client/team-members.mjs +41 -0
  103. package/packages/client/team-rows.mjs +45 -0
  104. package/packages/client/terminal-contract.mjs +57 -0
  105. package/packages/client/tmux-status.mjs +66 -0
  106. package/packages/client/waiting-on-you.mjs +88 -0
  107. package/packages/client/workspace-admission.mjs +45 -0
  108. package/packages/client/workspace-cli.mjs +142 -0
  109. package/packages/client/workspace-views.mjs +147 -0
  110. package/packages/tui/README.md +46 -0
  111. package/packages/tui/bin/tui.mjs +7 -0
  112. package/packages/tui/lib/actions.mjs +29 -0
  113. package/packages/tui/lib/client.mjs +4 -0
  114. package/packages/tui/lib/main.mjs +105 -0
  115. package/packages/tui/lib/term/keys.mjs +323 -0
  116. package/packages/tui/lib/term/screen.mjs +122 -0
  117. package/packages/tui/lib/term/style.mjs +43 -0
  118. package/packages/tui/lib/term/text.mjs +49 -0
  119. package/packages/tui/lib/term/tty.mjs +168 -0
  120. package/packages/tui/lib/term/width.mjs +124 -0
  121. package/packages/tui/lib/views/frame.mjs +62 -0
  122. package/packages/tui/lib/views/help.mjs +28 -0
  123. package/packages/tui/package.json +8 -0
  124. package/skills/oats-getting-started/SKILL.md +29 -22
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  127. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  128. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  129. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  130. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  131. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  132. package/lib/launch-prompt-policy.mjs +0 -87
@@ -125,6 +125,11 @@ Everything after `build` reads `MANIFEST.json` and the files already staged:
125
125
  does not run.
126
126
  - **Legs for hosts you do not have.** The Linux AppImage/DEB need a Linux
127
127
  host; the lane says so and `stage` lists what is missing.
128
+ - **The packaged window launch.** `release.yml` launches the packaged window
129
+ on its Linux leg, under xvfb. The lane's `desktop` phase launches nothing on
130
+ any host, so a lane release reports the Linux launch check as not run. The
131
+ obligation stays open until a hosted run (pushing the tag runs
132
+ `release.yml`) or a person's launch covers it.
128
133
 
129
134
  ## How it relates to `release.yml`
130
135
 
@@ -150,11 +155,16 @@ The macOS x64 leg cross-builds on macos-14 and installs Rosetta 2 so that its
150
155
  x64 Electron + node-pty ABI probe really executes; a wrong-architecture
151
156
  native module fails that leg.
152
157
 
153
- CI does **not** gate the packaged GUI launch: ad-hoc-signed, non-notarized
154
- Electron apps do not
155
- have a reliable interactive windowserver in headless CI. Post-publish launch
156
- acceptance is therefore owned by the operator/maintainer, using the actual
157
- released installers (not a source checkout):
158
+ CI launches the packaged window on the Linux leg only: `release.yml` and
159
+ `build-installers.yml` run the smoke once more with its launch phase, under
160
+ xvfb, and a window that does not reach the shell fails the leg. That is the
161
+ unpacked Linux build, not an installed AppImage or DEB. CI does **not** gate
162
+ the macOS launch: ad-hoc-signed, non-notarized Electron apps do not
163
+ have a reliable interactive windowserver in headless CI. The lane does not
164
+ launch the window: see
165
+ [What the lane cannot produce](#what-the-lane-cannot-produce). Post-publish
166
+ launch acceptance is therefore owned by the operator/maintainer, using the
167
+ actual released installers (not a source checkout):
158
168
 
159
169
  1. Verify the asset checksum/attestation, install it outside the source tree,
160
170
  and on macOS use right-click → **Open** for the Gatekeeper step (ad-hoc
@@ -32,7 +32,7 @@
32
32
  - Other model, billing, effort or permission banners after a submitted Enter
33
33
  still block (`E_SPAWN_INCOMPLETE`, `blocked`).
34
34
 
35
- See [configuration](../configuration.md#exact-home-launch-prompt-consent)
35
+ See [configuration](../configuration.md#the-development-channel-confirmation)
36
36
  and [recovery](../execution-targets.md#launch-prompt-outcomes).
37
37
  - **The Desktop shows launch-prompt consent and retained launches**
38
38
  ([#711](https://github.com/awebai/oats/issues/711)). The spawn dialog shows a
@@ -0,0 +1,156 @@
1
+ # OATS 0.51.0
2
+
3
+ 2026-10-11
4
+
5
+ ## Added
6
+
7
+ - **`oats session attach --detach-key <key>`: a key that leaves the viewer
8
+ (#856).** A viewer sets no tmux prefix and a locked key table, so every key
9
+ reaches the agent and nothing on the keyboard leaves it. A caller may now
10
+ name one key that detaches its own viewer, on the local form and with
11
+ `--server`. The agent's window and every other viewer are untouched, and
12
+ the agent never receives that key while this viewer is attached. Nothing
13
+ changes for a caller that names none: a plain attach still has no keyboard
14
+ exit, the tmux prefix included, and is left by closing the terminal.
15
+ - **The key** is `C-` with a letter other than `h`, `i` and `m` or one of
16
+ `\ ] ^ _`, `M-` with a lowercase letter or a digit, or `F1` to `F12` with
17
+ at most one of `C-`, `M-`, `S-`. Anything else is `E_BAD_ARGS` before any
18
+ tmux or ssh call. The suggested key is `C-\`, written `--detach-key
19
+ 'C-\'`; `F12` where `\` needs AltGr.
20
+ - **Exit status 20** when the viewer was left by the key. 0 (the viewer
21
+ ended without the key) and 1 (a refusal, or tmux failing under the
22
+ viewer) are unchanged, and so is ssh's own 255 on the routed form. 20 is
23
+ nonzero, so `set -e`, an `&&` chain and tmux's `remain-on-exit failed`
24
+ treat a leave by the key as a failure.
25
+ - **While the pane is scrolled back**, tmux's copy mode reads its own key
26
+ table first: a key copy mode binds (`C-e`, for example) detaches only
27
+ once the mode is left. `C-\` and `F12` are unbound in tmux's default
28
+ copy-mode tables (3.7c) and detach from there.
29
+ - **Feature `session-attach-detach-key`** in `oats version --json`, and so
30
+ in `oats status --json` and each `oats server roster --json` group's
31
+ `probe.features`. Gate on it and never try: a kernel without the feature
32
+ ignores the flag and opens a viewer with no exit. A routed attach sends
33
+ the flag only to a host that advertises the feature, and probes for it
34
+ under `--print` too. A host without it is refused here with
35
+ `E_REMOTE_INCOMPATIBLE`, exit 1, nothing else sent; its `details` are
36
+ `{"feature":"session-attach-detach-key"}`.
37
+
38
+ See [Inspect, input and
39
+ attach](../execution-targets.md#inspect-input-and-attach) and
40
+ [servers.md](../servers.md#run-there).
41
+
42
+ ## Changed
43
+
44
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.52.0`.** The compatibility band
45
+ admits 0.51. Upgrade the CLI and the Desktop together: a 0.50.0 Desktop
46
+ refuses a 0.51.0 CLI. No feature gate changes: the Desktop does not use
47
+ `--detach-key`, and it already words `E_LIFECYCLE_BUSY`, the answer a second
48
+ retire of an instance now gets.
49
+
50
+ - **oats.okf 5.0.1: collision-safe harvest publication**
51
+ ([oats-okf#63](https://github.com/awebai/oats-okf/pull/63), fixes
52
+ [#62](https://github.com/awebai/oats-okf/issues/62) and
53
+ [#60](https://github.com/awebai/oats-okf/issues/60)). The official catalog,
54
+ reference workspace and generated mirrors take published `v5.0.1` at
55
+ `96b28d5cd4f01e48ed50d8e999e8715749a99e87`. Harvest refs use a fixed
56
+ prefix, UTC date and fresh UUID, not a source/harvester name. Git validates
57
+ the full ref; a create-only push plus new-ref confirmation refuses both
58
+ divergent and identical pre-existing targets without overwriting or retrying.
59
+ Source provenance remains in the commit and PR. A publication failure
60
+ **keeps the live harvester home**, with exact diagnostics and clone/commit/
61
+ PR-text locations, and notifies the reachable source through its existing
62
+ messaging. No standing-maintainer recipient or messaging preflight is
63
+ added; existing attention is used where supported. Missing/failed messaging
64
+ cannot turn failure into retirement. Partial or uncertain gh publication
65
+ stays live and does not authorize retries or remote cleanup.
66
+ The OATS floor remains `>=0.29.0`; old homes retain their copied modules
67
+ until respawn. No pre-5.0 source migration or new custody engine is included.
68
+ See [Knowledge](../knowledge.md#the-flow).
69
+
70
+ - **oats.framework 1.9.1: oats.core 2.5.1.** Instruction text only; no
71
+ kernel, schema or provider contract changes. `oats-operate` says that a
72
+ plain `oats session attach` has no keyboard exit, and that
73
+ `--detach-key <key>` leaves the viewer on a kernel whose
74
+ `oats version --json` lists `session-attach-detach-key` (#856). The
75
+ capability floors are unchanged. A deployment takes it at the tag
76
+ `oats-framework/v1.9.1`; a running instance keeps the text it was spawned
77
+ with until it is respawned.
78
+
79
+ - **oats.aweb 1.24.1: `setup --join` on a closed workspace**
80
+ ([oats-aweb#95](https://github.com/awebai/oats-aweb/pull/95)). The official
81
+ catalog, reference workspace and generated `mirrors/oats-aweb` take published
82
+ `v1.24.1` at `4212db16668c9bd837d7d99f287ed9e9ae303a0e`. On a workspace that
83
+ forbids local team writes, `oats aweb setup --join <label>` refuses only when
84
+ its plan would write a mapping or a default. A label the workspace already
85
+ commits to the joined team, and already its default, joins and records its
86
+ minting root without touching the team configuration. A conflicting mapping or
87
+ another configuration failure is reported as that (`E_SETUP_TEAM_CONFLICT`,
88
+ `E_SETUP_CONFIGURATION`) instead of `E_SETUP_POLICY`, and still refuses before
89
+ any write. Known limit: joining a second committed team on a closed workspace
90
+ whose default is another label still refuses
91
+ ([oats-aweb#96](https://github.com/awebai/oats-aweb/issues/96)). The OATS
92
+ floor stays `>=0.42.0`; old homes keep their copied modules until respawn.
93
+
94
+ ## Fixed
95
+
96
+ - **Retire: one retire of an instance at a time (#863).** Two `oats retire`
97
+ of the same instance, started moments apart from two sessions, both ran to
98
+ completion: two recovery copies, and every capability's retire hook ran
99
+ twice, at the same time. A retire hook releases things that exist once (a
100
+ messaging identity, a scheduled job). A retire now holds the instance's
101
+ claim from the moment it has resolved the home until it ends, and any other
102
+ retire of that instance is refused at once with `E_LIFECYCLE_BUSY` (exit 1),
103
+ before it stops a session or a child, writes a recovery, runs a hook or
104
+ changes a file of the home: `a retire of <name> is already running (pid
105
+ <pid>, since <at>); nothing was done — wait for it to finish`. This holds
106
+ for a plain retire, a guarded apply with any idempotency key, `--self` and
107
+ its detached completion, and `--server`; `--force` does not bypass it, and
108
+ `--plan` is unchanged. `details` is `{instance, home, lock, pid, since}`.
109
+ A guarded apply answers it whatever its plan would read by then: the plan
110
+ its revision is checked against is now read once the retire holds the
111
+ claim, so a retire in flight, which has usually changed the plan already,
112
+ is answered as busy and not as `E_PLAN_STALE`. A stale apply with nobody
113
+ else retiring answers `E_PLAN_STALE` as before.
114
+ - **A scheduled `--self` counts.** From the moment a self-retire is
115
+ scheduled until its completion has ended, every other retire of the
116
+ instance is refused the same way (`a retire of <name> is already
117
+ scheduled …`, `details.lock` the pending marker). The marker
118
+ `.oats-retire-pending-<instance>.json` now records the completion process
119
+ (`completionPid`, `completionStart`). A completion that failed or died
120
+ refuses nothing: `oats retire <instance>` retries it, as before. A second
121
+ `--self` answers `alreadyScheduled: true` while the completion has not
122
+ started (see the changed answers below).
123
+ - **The claim file** is
124
+ `<agents>/<agent>/instances/.oats-retirement/claims/<instance>.lock`,
125
+ beside the homes, and names its holder by pid and start time. A retire
126
+ that ends leaves none. A retire that was killed leaves its file until
127
+ that name is retired again: the next retire takes the claim over, because
128
+ its holder is verifiably gone. The file is safe to remove by hand once
129
+ its pid is gone. The claim does not end what a killed retire left
130
+ running: one of its retire hooks may still be running when the next
131
+ retire takes the claim over and runs the hooks again (#865).
132
+ - **A host that cannot read a process's start time** (no `/proc`, and `ps`
133
+ failing): a retire could not hold its claim verifiably there, so it is
134
+ now refused with `E_LIFECYCLE_BUSY`, and the message says what could not
135
+ be read. Likewise a claim or a pending marker whose holder's start cannot
136
+ be read is never taken for gone: the refusal names the pid, the file and
137
+ the way out (check that pid by hand; if it is not an `oats retire`,
138
+ remove the file, then retry).
139
+ - **Two changed answers**, both `E_LIFECYCLE_BUSY` where the answer was
140
+ `alreadyScheduled: true`. A second `--self` gets it while the first is
141
+ still scheduling, and once the completion has started and holds the
142
+ claim: it answers `alreadyScheduled: true` only between the two, while
143
+ the completion has not started. And `--self --keep-dir` runs the retire in
144
+ the calling process, so it is refused while a `--self` completion is
145
+ pending: on a home opened in Herdr (removed in 0.31.0), where `--self
146
+ --keep-dir` is deferred like a plain `--self`, a second one inside that
147
+ window gets it too.
148
+
149
+ The claim orders retires only: `oats instance stop`, `oats session start`
150
+ and `oats worktree add` against a retire in flight are unchanged (#866). See
151
+ [Retire](../desktop-cli-api.md#retire).
152
+
153
+ - **A retire, and anything else that reads a process's start, no longer
154
+ depends on the caller's `PATH` for `ps` (#878):** it runs the system `ps`
155
+ from `/usr/bin:/bin`, so a retire whose `PATH` holds no `ps` is no longer
156
+ refused with `E_LIFECYCLE_BUSY` (`ps could not be run (ENOENT)`).