@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
package/docs/schedules.md CHANGED
@@ -21,8 +21,10 @@ inside the deployment, including from an instance home, sees the same
21
21
  definitions.
22
22
 
23
23
  There is no daemon. One host timer (a launchd user agent on macOS, a systemd
24
- user timer on Linux) runs `oats schedule tick --host` once a minute. The tick
25
- evaluates only the current minute, launches what is due through the same
24
+ user timer on Linux) runs `oats schedule tick --host` at second 0 of every
25
+ minute. The tick evaluates only the minute it was fired for (read from the
26
+ process's own start, before any other work, so a tick that is slow to start
27
+ still evaluates its minute), launches what is due through the same
26
28
  `spawn`, `session start` and `session input` paths you use by hand, polls the
27
29
  triggers that are due, records what it observed, and exits. Minutes missed
28
30
  while the machine slept are skipped, never replayed; there are no retries and
@@ -110,7 +112,8 @@ refuses the key on a trigger.
110
112
  scheduler keeps the unknown attempt and its slot until reconciliation.
111
113
  - **wake** `{…, home, message}` — every due minute inspects the instance at
112
114
  `home`. Running: `message` is delivered once as terminal input (bracketed
113
- paste plus Enter), never an interrupt. Not running: the home is started with
115
+ paste plus Enter), never an interrupt. Not running (its harness exited, or
116
+ its tmux server is gone after a reboot): the home is started with
114
117
  `session start` and the message becomes the job's one pending delivery,
115
118
  completed on a later tick once the session is active; the home is started
116
119
  again only at due minutes, so a harness that keeps exiting is not restarted
@@ -585,6 +588,7 @@ oats schedule reconcile <id> [--clear] # resolve an attempt whose result was n
585
588
  oats schedule host install # register this deployment and install the one host timer (idempotent)
586
589
  oats schedule host install --max-concurrent 3 --triggers-max-concurrent 2
587
590
  oats schedule host install --max-concurrent default --triggers-max-concurrent none
591
+ oats schedule host install --print [--os darwin|linux] # what install would write; changes nothing
588
592
  oats schedule host status | uninstall
589
593
  oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?" # or --wake-file spec.json
590
594
  ```
@@ -638,6 +642,74 @@ five. Correct it with `oats schedule host install --max-concurrent N` (or
638
642
  An absent value still means five. Set caps through the CLI; do not edit the
639
643
  registry by hand.
640
644
 
645
+ ### The host timer's unit
646
+
647
+ The unit is a launchd user agent (`~/Library/LaunchAgents/ai.oats.schedule-tick.plist`,
648
+ `StartCalendarInterval` with an empty dict) or a systemd user timer and service
649
+ (`oats-schedule-tick.timer`, `OnCalendar=*-*-* *:*:00`, `AccuracySec=1s`,
650
+ `Persistent=false`). Both fire at second 0 of every minute; the launchd job is
651
+ `ProcessType Standard`, not `Background`, whose throttling delayed its start
652
+ under load. The tick evaluates the minute it was fired for as long as it starts
653
+ within that minute. A tick still running when the next minute fires loses that
654
+ minute's fire, on both platforms: launchd and systemd do not start a job that is
655
+ still running, and nothing replays the minute (#902's bounded catch-up, a
656
+ separate change, is what recovers it). `install` renders it
657
+ from **the environment of the shell it runs in**, so run it from the operator's
658
+ own shell, not from an instance home:
659
+
660
+ - **PATH**: the directory of the node the unit runs, then the installer's
661
+ `PATH`, then `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`,
662
+ `/usr/sbin` and `/sbin`. Three kinds of entry are dropped from the
663
+ installer's `PATH`: entries inside an OATS instance home (an instance's
664
+ `.oats/bin`, or anything under `$OATS_INSTANCE_HOME`), entries inside a
665
+ versioned Homebrew keg (`…/Cellar/<formula>/<version>/…`), and relative or
666
+ empty entries. An entry that does not exist yet is kept. This is the
667
+ `PATH` the tick itself runs with. A harness the tick launches is looked up
668
+ where its pane will look it up
669
+ ([execution targets](execution-targets.md#the-servers-start-environment)):
670
+ a launch configuration's own `PATH` when it sets one, else the running OATS
671
+ tmux server's `PATH`, or, when the tick is what starts the server, the
672
+ `PATH` of the login environment the server is created with. The
673
+ unit's `PATH` is that lookup's fallback, when the login environment cannot
674
+ be read.
675
+ - **node**: the keg's `<prefix>/opt/<formula>/bin/node` when it is the node
676
+ running `install`, else the first `node` on the filtered `PATH` that is that
677
+ same file. When neither exists, `install` keeps the node's own path and its
678
+ answer carries a warning that the path is not stable. Only Homebrew's `opt`
679
+ link survives an upgrade. With a version manager (mise, nvm, asdf, fnm) the
680
+ node on `PATH` is that version's own install, so the unit records that
681
+ version's path, and `host status` reports `node-missing` once that version
682
+ is removed.
683
+ - **oats**: the `oats.mjs` of the oats that runs `install`. When that is inside
684
+ `$OATS_INSTANCE_HOME` or its `work` (a clone in an instance's work tree,
685
+ an attached instance's included), `install` and
686
+ `--print` warn: the timer would stop when that instance retires. Run
687
+ `install` with the operator's installed oats.
688
+
689
+ An installed unit changes only when `install` runs again. `install` rewrites a
690
+ unit whose bytes differ, so running it again after an upgrade migrates the
691
+ unit. `oats schedule host install --print` writes to stdout exactly what
692
+ `install` would write, each file under a `==> <path> <==` line, and changes
693
+ nothing: no registry, no unit file, no log directory, no `launchctl` or
694
+ `systemctl` call. `--os darwin|linux` renders another platform's unit. With
695
+ `--json` it answers `{kind, files: {<path>: <content>}, warnings}`.
696
+
697
+ `host status` (and the `scheduler` of every list) carries `problems`, warnings
698
+ that never change `installed` or `active`. Each is `{code, message, fix}`, read
699
+ from the installed unit alone, so every caller gets the same answer:
700
+
701
+ | Code | When |
702
+ | --- | --- |
703
+ | `node-missing` | the node the unit runs does not exist |
704
+ | `oats-bin-missing` | the `oats.mjs` the unit runs does not exist |
705
+ | `path-entry-missing` | an entry of the unit's `PATH` does not exist (one problem per entry; the fixed prefixes above are not checked, nor the missing node's own directory) |
706
+ | `unit-outdated` | the unit fires on an interval (`StartInterval`, `OnUnitActiveSec`), or differs from what this oats renders for the same node, oats, `PATH` and `OATS_HOME_DIR` |
707
+
708
+ Each problem's `fix` says what to do. For `path-entry-missing`, restore the
709
+ entry, or remove it from the operator's `PATH` and run `oats schedule host
710
+ install` again; for the others, run `oats schedule host install` again from
711
+ the operator's shell.
712
+
641
713
  `oats schedule list --json` answers:
642
714
 
643
715
  ```text
@@ -647,7 +719,7 @@ registry by hand.
647
719
  schedules: [ <row> ],
648
720
  triggers: { count, command: "oats trigger list" },
649
721
  snapshot: { takenAt, problems } | null,
650
- scheduler: { installed, active, unit?, lastTick, maxConcurrent, triggersMaxConcurrent, tickIntervalSec,
722
+ scheduler: { installed, active, unit?, problems, lastTick, maxConcurrent, triggersMaxConcurrent, tickIntervalSec,
651
723
  workspace, registered, workspaces, live } }
652
724
  ```
653
725
 
@@ -668,6 +740,21 @@ home whose retirement is pending still counts), `ended` (its home is gone),
668
740
  you), `launch-failed`, `unknown`, and for wake jobs `delivered`, `started` or
669
741
  `skipped`. The kernel never claims a task succeeded.
670
742
 
743
+ A home whose recorded tmux server is gone, after a reboot or a crash, is
744
+ `stopped` too, with the note `its tmux server is gone`. Gone means that no
745
+ server listens on its socket, or that its socket file is missing and no
746
+ process works in the home. When a process still works there, the home stays
747
+ `unknown`, with that reason
748
+ ([missing socket](execution-targets.md#missing-socket)). A spawn job keeps
749
+ its slot while its instance's home exists, a stopped one included (its harness
750
+ exited, or its tmux server is gone), so its due minutes are skipped with
751
+ `previous instance stopped: retire it (oats retire <instance>) or start it
752
+ again (oats session start --home <home>)`, and
753
+ `oats schedule run-now` refuses with the same words (`E_SCHEDULE_RUNNING`).
754
+ While the instance runs, they are skipped as `still running`. After a reboot, a wake job
755
+ starts its instance's session at its next due minute, and a spawn job shows
756
+ `stopped` with the command to retire or start its instance.
757
+
671
758
  `unknown` means the launch's side effects are unconfirmed: a command timed out
672
759
  or answered no envelope, or an attempt was never recorded. A job with a
673
760
  persisted attempt is skipped until `oats schedule reconcile <id>` (an
package/docs/servers.md CHANGED
@@ -180,12 +180,16 @@ Every routed ssh call carries these options, before `--` and the host:
180
180
  - When ssh fails under an attached viewer (a lost link, or one never made),
181
181
  `session attach --server` exits 255 and says that, if the link was lost,
182
182
  the instance keeps running on the server, with the command to reattach.
183
+ When `--detach-key` was given, that command carries it (` --detach-key
184
+ <key>`, shell-quoted); without one the line is as before.
183
185
  When ssh fails before the viewer opens (the version probe, or a name
184
186
  resolved through the host's roster), it also exits 255, with `oats: ssh to
185
187
  <host> failed: …` (`--json`: the `E_SSH` envelope). Every other refusal
186
188
  (an incompatible host, an unknown or ambiguous name, bad arguments) exits 1,
187
189
  and so does an ssh that cannot be run on this machine at all: no link can
188
- come back.
190
+ come back. Otherwise the host's own status is relayed through ssh: 20 when
191
+ the viewer was left by its detach key (`--detach-key`, below), 0 when it
192
+ ended without the key, 1 for a refusal or a tmux failure there.
189
193
  - Every routed command reports ssh's own failure as `E_SSH` (`ssh to <host>
190
194
  failed: …`). When ssh never started on this machine, the `--json` envelope
191
195
  says so with `error.details: {"sshStarted": false}`; without details, ssh
@@ -210,7 +214,7 @@ sent as text or on stdin, never as paths.
210
214
  | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule |
211
215
  | `status` | registered workspace | |
212
216
  | `retire` | the instance's home | `retire-home` to retire by exact home |
213
- | `session inspect`, `session attach` | the instance's home | `session` |
217
+ | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key` |
214
218
  | `session start`, `session restart` | the instance's home | `session-start`; `session-restart`; `launch-config` when `--launch-config`, `--harness` or `--yolo` is given |
215
219
  | `session upload` | the instance's home | `session-upload` |
216
220
  | `okf harvest --instance <name>` | the saved home | `harvest` |
@@ -271,6 +275,21 @@ side answers one envelope (`E_SSH`, or `E_REMOTE_ENVELOPE`). Wherever this
271
275
  side prints the argv, `--invite` values are replaced by `<redacted>`.
272
276
  Kernel commands keep the table above.
273
277
 
278
+ **A detach key on a routed attach.** `session attach --server <id>
279
+ --detach-key <key>` names the key that leaves the viewer, as on the host
280
+ itself ([execution-targets.md](execution-targets.md#inspect-input-and-attach):
281
+ the grammar, the suggested `'C-\'`, exit status 20). The key is checked here
282
+ first, before any ssh call (`E_BAD_ARGS`). The flag travels only to a host
283
+ that advertises `session-attach-detach-key`: a kernel without the feature
284
+ would ignore it and open a viewer with no exit. Such a host is refused on
285
+ this machine after the version probe, with nothing else sent, exit 1:
286
+ `E_REMOTE_INCOMPATIBLE`, `remote oats <version> at <host> does not advertise
287
+ session-attach-detach-key; upgrade it there, or attach without --detach-key;
288
+ nothing was sent`. Under `--json` the envelope's `error.details` is
289
+ `{"feature":"session-attach-detach-key"}`. With a key the probe also runs
290
+ under `--print`, which otherwise skips it: a printed command must not carry
291
+ a flag its host would ignore.
292
+
274
293
  **Not routed.** `session input` runs on the execution host, where schedules
275
294
  and messaging capabilities call it. `session restart --stop-grace` is refused
276
295
  with `--server`; the remote default applies. `session attach --print` shows
@@ -218,20 +218,25 @@ instructions and pins model/provider settings; it excludes nothing.
218
218
  Claude Code and Codex ask before they work in a folder they have not seen, and
219
219
  every instance home is new. A launch stopped at that prompt waits for a human,
220
220
  so the operator trusts the **deployment directory** (where `oats-local.yaml`
221
- is) once per harness. Launches only read native configuration. The explicit
222
- `oats harness trust --dir D --harness all --plan` previews the entry; the same
223
- command without `--plan` applies it with a deployment audit. See
224
- [native trust](harness-trust.md) for safe operation and partial-failure recovery.
221
+ is) once per harness configuration file. Launches only read native
222
+ configuration. The explicit `oats harness trust --dir D --plan` previews the
223
+ entry in every file a launch reads: the ambient one and each launch
224
+ configuration's `CLAUDE_CONFIG_DIR` / `CODEX_HOME`. The same command without
225
+ `--plan` applies it with a deployment audit; it never creates a launch
226
+ configuration's directory. See [native trust](harness-trust.md) for safe
227
+ operation and partial-failure recovery.
225
228
 
226
229
  - **Claude Code** looks for an accepted entry for its folder or an ancestor, up
227
230
  to a Git root. An intervening repository can prevent deployment-root inheritance;
228
231
  the command does not automatically trust another root. The native field is
229
232
  `projects["<deployment>"].hasTrustDialogAccepted` in `~/.claude.json`
230
- (`$CLAUDE_CONFIG_DIR/.claude.json` when that is set).
233
+ (`$CLAUDE_CONFIG_DIR/.claude.json` when the launch's environment, host or
234
+ launch configuration, sets it).
231
235
  - **Codex** applies only an exact entry: a trusted parent does not cover the
232
236
  folders below it. The explicit deployment-root command records
233
237
  `[projects."<deployment>"] trust_level = "trusted"` in
234
- `~/.codex/config.toml` (`$CODEX_HOME/config.toml`). With that entry, or one
238
+ `~/.codex/config.toml` (`$CODEX_HOME/config.toml`, from the launch's
239
+ environment as for Claude). With that entry, or one
235
240
  for an ancestor of the deployment, each codex launch trusts its own new home
236
241
  for that session (`-c 'projects={"<home>"={trust_level="trusted"}}'`) and
237
242
  leaves the config file unchanged. A yolo launch always does this. The plan
@@ -239,14 +244,16 @@ command without `--plan` applies it with a deployment audit. See
239
244
  - Every codex launch also passes `-c check_for_update_on_startup=false`, so
240
245
  Codex's "Update available" choice cannot block it.
241
246
 
242
- When a claude or codex home is not covered, the spawn says so (text and
243
- `--json` `warnings`): `the <harness> session will stop at its folder-trust
244
- prompt: trust <deployment> once (<the step>)`. `oats readiness` reports the
245
- same in `checks.configured` (code `harness-trust`, not required).
247
+ When the file a claude or codex launch reads does not trust the deployment,
248
+ the spawn says so (text and `--json` `warnings`): `<harness> folder trust is
249
+ not established in <file>: oats harness trust --dir <deployment>`. A missing
250
+ entry does not prove a prompt, so it does not say the session will stop.
251
+ `oats readiness` reports the same in `checks.configured` (code
252
+ `harness-trust`, not required), and a passing item naming the file when trust
253
+ is established.
246
254
 
247
- Exact-home [aweb development-channel consent](configuration.md#exact-home-launch-prompt-consent)
248
- does not cover folder-trust prompts. It neither writes trust settings nor
249
- enables existing homes automatically.
255
+ [The development-channel confirmation](configuration.md#the-development-channel-confirmation)
256
+ does not cover folder-trust prompts, and never writes trust settings.
250
257
  A blocked or incomplete prompt outcome preserves the home and process even
251
258
  though its metadata says `launched:false`; inspect that endpoint before any
252
259
  recovery. See [launch prompt outcomes](execution-targets.md#launch-prompt-outcomes).
@@ -434,12 +441,59 @@ takes a final capture of notes and the session record into durable custody; an
434
441
  incomplete capture keeps the home for a retry. Retirement never waits for a
435
442
  model or GitHub: processing continues after the home is gone.
436
443
 
444
+ One retire of an instance runs at a time. A retire holds the instance's claim
445
+ from the moment it has resolved the home until it ends: the file
446
+ `.oats-retirement/claims/<instance>.lock` in the agent's instances directory,
447
+ beside the homes, which names its holder by pid and start time. Any other
448
+ retire of that instance (plain, guarded or `--self`, `--force` included) is
449
+ refused at once with `E_LIFECYCLE_BUSY`, before it stops anything, copies
450
+ anything or runs a hook: a retire hook releases things that exist once, such
451
+ as a messaging identity or a scheduled job. A self-retire's completion is
452
+ refused the same way, after it has waited up to 3 s for the retire that
453
+ scheduled it to release the claim. A self-retire that is scheduled counts from the moment it is scheduled,
454
+ while its completion lives. A retire killed while it holds the claim leaves
455
+ the file behind until that name is retired again: the next retire takes the
456
+ claim over, because its holder is verifiably gone, and the file is safe to
457
+ remove by hand once its pid is gone. A holder that was killed and that its
458
+ parent has not reaped (a zombie) is gone too: nothing waits for that reap. The claim does not end what the killed
459
+ retire left running: one of its retire hooks may still be running when the
460
+ next retire takes the claim over and runs the hooks again (#865). A holder whose start time cannot be
461
+ read is never taken for gone; the refusal names the pid, the file and the
462
+ way out.
463
+
464
+ A stop holds the same claim (OATS 0.52.0, #866, #890). `oats instance stop
465
+ <instance> --apply` takes the claim of the instance and of every recorded
466
+ child it would stop before it stops the first one, and holds them until it
467
+ has written its receipt. So a stop and a retire of one instance never run
468
+ together: a stop that meets a retire is refused with `E_INSTANCE_RETIRING`, a
469
+ retire or a stop that meets a stop with `E_LIFECYCLE_BUSY`, at once and
470
+ before anything is stopped, run, copied or written. A stop that is killed
471
+ leaves its claim files, and they refuse nothing: the next stop or retire
472
+ takes them over. Before 0.52.0 a stop marked the home with a file inside it,
473
+ `.oats-stop-pending.json`, that named no holder: a killed stop left every
474
+ later stop of that instance refused until the file was removed by hand, and
475
+ a stop wrote into a home that a retire was inspecting or removing. That
476
+ name stays reserved: a file an older OATS left there refuses nothing and is
477
+ removed by the next stop. A retire does not hold the claims of its recorded
478
+ children: it stops each one, and that stop takes the child's claim for as
479
+ long as it lasts; a child held by someone else's stop or retire is a child
480
+ that did not stop (below). `oats worktree add` reads the claim and is
481
+ refused while a retire of the home runs (`E_INSTANCE_RETIRING`). `oats
482
+ session start` and `restart` do not read it yet, and `oats status` does not
483
+ show it. Who answers what to whom is one table in
484
+ [desktop-cli-api.md](desktop-cli-api.md#lifecycle-pairs); the refusals of a
485
+ retire are in [desktop-cli-api.md](desktop-cli-api.md#retire).
486
+
437
487
  Recorded children (the instances whose recorded parent chain reaches this
438
488
  one) are stopped first, never escalated, and kept: their homes stay. If one is
439
489
  still running after the grace, or its stop cannot be established, retire
440
490
  refuses with `E_CHILDREN_RUNNING` and retires nothing; `--force` does not
441
491
  bypass it. This holds for plain, guarded and `--self` retires alike
442
- ([desktop-cli-api.md](desktop-cli-api.md)).
492
+ ([desktop-cli-api.md](desktop-cli-api.md)). Who is a child is read from each
493
+ home's `instance.json`: a home whose record cannot be read is never stopped
494
+ as anyone's child, by a retire or by `oats instance stop`. Its session may go
495
+ on running after its parent is retired, and the retire's answer does not name
496
+ it; `oats status` is where it shows.
443
497
 
444
498
  Before any retire hook runs, retire preserves the instance's uncommitted and
445
499
  unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
@@ -796,6 +850,40 @@ a file over 2 GiB it gives the size, and `find <work> -type f -size
796
850
  or make it readable, then run `oats retire <instance>` again. With nothing to
797
851
  preserve, the files are not read and the retire goes through.
798
852
 
853
+ **A home whose `instance.json` cannot be read.** The record is what
854
+ identifies a home: its soul, its work mode, its session, its lineage. One
855
+ that is there and gives no JSON object (a write cut off, an empty file, a
856
+ file kept from the user, a directory or a dangling link in its place, JSON
857
+ that is not an object) decides only for that home. `oats status` lists the
858
+ home with `unknown` and `E_UNIDENTIFIED_INSTANCE_HOME: <home>/instance.json
859
+ cannot be read (<reason>)`, and every other instance is listed, stopped,
860
+ started and retired as if that home were not there. The home's own retire
861
+ (`--plan` and `--force` included), its stop and its session start are refused
862
+ with `E_UNIDENTIFIED_INSTANCE_HOME` before anything is read, stopped, run or
863
+ removed. `--force` removes a home that has no `instance.json`; it does not
864
+ remove one whose record cannot be read, which may be a whole instance with
865
+ work. Restoring the file from a copy makes the home usable again; removing
866
+ such a home through OATS is not possible yet. A parent whose record cannot be
867
+ read has no recorded children for a stop or a retire: the lineage is read
868
+ from records, so its children are listed and act on their own. In the other
869
+ direction, such a home is never stopped as anyone's child: stop it, once its
870
+ record is restored, on its own. The answers are in
871
+ [desktop-cli-api.md](desktop-cli-api.md#unreadable-record).
872
+
873
+ **An entry of the home that cannot be read, or that is gone when it is
874
+ read.** Each inspection walks the home: it lists a directory, then reads each
875
+ entry. A file or a directory without permission, and an entry that another
876
+ process removed or renamed between the listing and the read, refuse the
877
+ retire with `E_WORK_INSPECTION_FAILED` at the inspection that met it. The
878
+ message names the entry and the system's reason, and ends with what the
879
+ retire had done by then, as the other refusals at that point do: nothing was
880
+ stopped, run or removed at the first inspection; no hook has run and nothing
881
+ was deleted at the one before the hooks; the hooks have run, and the home, its
882
+ work and the pre-hook recovery are kept at the one after them. The home is
883
+ kept in each case. Make the entry readable, or let the process that writes in
884
+ the home end, then run `oats retire <instance>` again. The answer says the
885
+ same as data: [`error.details.reached`](desktop-cli-api.md#retire-reached).
886
+
799
887
  The home is not copied again because the work is, and the work is not copied
800
888
  again because the home is. The home's comparison after the hooks holds every
801
889
  entry the home copy carries, as its bytes and permission bits, the kernel's
@@ -939,7 +1027,7 @@ can be inspected, and it is the process the scan exists to find.
939
1027
  or briefing says it is done. A live harness cannot give a stable final
940
1028
  inspection of its own work, so the calling process inspects, runs, and removes
941
1029
  nothing: it records the intent beside its home as
942
- `.oats-retire-pending-<instance>.json` and starts a detached completion, then returns so the instance can report final
1030
+ `.oats-retire-pending-<instance>.json`, which names the completion process, and starts a detached completion, then returns so the instance can report final
943
1031
  status before its tmux window dies a few seconds later. The completion then
944
1032
  retires the instance exactly as an external `oats retire` would: quiesce the
945
1033
  harness, preserve uncommitted work, run retire hooks, repair lineage, remove
@@ -1092,10 +1180,11 @@ the new path.
1092
1180
  with each, and they are part of the plan's revision: a tree created, removed,
1093
1181
  dirtied or cleaned between the plan and a guarded apply, or a new target for
1094
1182
  it, refuses the apply with `E_PLAN_STALE` before anything runs. The retire
1095
- checks the trees again at the step itself and refuses with `E_PLAN_STALE`,
1096
- keeping the home, rather than move or remove a tree in a way the plan did
1097
- not say. The retire hooks have run by then, and no tree was moved or
1098
- removed. The fields are in
1183
+ checks the trees again at the step itself and refuses with
1184
+ `E_WORK_PRESERVATION_FAILED`, keeping the home, rather than move or remove a
1185
+ tree in a way the plan did not say. The retire hooks have run by then, and
1186
+ no tree was moved or removed; that is why the code is not `E_PLAN_STALE`,
1187
+ which says that nothing happened (it was, before OATS 0.52.0). The fields are in
1099
1188
  [the CLI API](desktop-cli-api.md#retire).
1100
1189
 
1101
1190
  #### After a retire: inspect, restore, dispose
@@ -1420,7 +1509,8 @@ and hooks, and fetches and writes nothing.
1420
1509
  A process is "still running" when its pid runs with the recorded start
1421
1510
  time. It counts as gone only when its pid does not run (the operating
1422
1511
  system says no such process: `kill -0` fails with ESRCH), or runs with another
1423
- start. When the start cannot be read (for example where `ps` fails), the
1512
+ start, or is a zombie: it has exited or was killed, and its parent has not
1513
+ reaped it. When the start cannot be read (for example where `ps` fails), the
1424
1514
  process is never taken for gone. `add` and `remove` refuse with
1425
1515
  `E_LIFECYCLE_BUSY`, naming the pid and the exact file to remove by hand once
1426
1516
  you have checked it: the record `.oats/trees/<p>.json`, or the claim
@@ -1441,7 +1531,9 @@ A claim left by a command that was killed is taken over by the next one,
1441
1531
  once its holder (pid and start time) is verified gone. Any git step the
1442
1532
  killed command left running is ended first, so it cannot finish late on
1443
1533
  the new tree. A quarantined
1444
- home or one being retired is refused (`E_INSTANCE_RETIRING`).
1534
+ home or one being retired is refused (`E_INSTANCE_RETIRING`): one for which
1535
+ a self-retire is scheduled, and, from OATS 0.52.0, one whose retire is
1536
+ running (the add reads the home's claim and takes nothing).
1445
1537
 
1446
1538
  **`remove`** runs `git worktree remove` (without `--force`) and `git worktree
1447
1539
  prune` on a tree `add` recorded, then drops the record. It keeps the branch
package/docs/tui.md ADDED
@@ -0,0 +1,152 @@
1
+ # OATS TUI (preview)
2
+
3
+ `oats tui` is the OATS terminal client: one full-screen, keyboard-only program
4
+ for people who work in terminals and on machines with no display, such as a
5
+ build host reached over ssh. The [OATS Desktop](desktop.md) is the client for
6
+ people who want a window; `oats tui` is the same kind of client for a
7
+ terminal. It ships inside the `oats` package: there is nothing else to
8
+ install.
9
+
10
+ ## It is a preview
11
+
12
+ `oats tui` is marked **preview**. That means:
13
+
14
+ - **This version draws the frame only.** It shows the frame, answers `?`
15
+ (help) and `q` (quit), and reads nothing from the kernel yet. The views
16
+ (instances, souls, capabilities) arrive in later releases.
17
+ - **Its screens and its configuration file may change without notice** while
18
+ it is a preview. Its configuration file, `tui.json`, does not exist yet.
19
+ - **It leaves preview when three things hold:** the readers it shares with
20
+ the Desktop are in their shared home (`packages/client/`), a person has
21
+ used it for a working day, and both maintainers agree to drop the mark.
22
+
23
+ Every other `oats` word keeps its contract. Nothing gates on `oats tui`:
24
+ `oats version --json` lists no feature for it.
25
+
26
+ ## Start it
27
+
28
+ ```bash
29
+ oats tui # in a terminal of 80x24 or more
30
+ oats tui --ascii # rules and marks in ASCII, whatever the locale
31
+ oats tui --help # the usage; needs no terminal
32
+ ```
33
+
34
+ It needs a terminal on both stdin and stdout, and a `TERM` that is set and is
35
+ not `dumb`. It draws from 60×15 up; on a smaller terminal it shows one line
36
+ with the size found and the size needed, and draws the frame again as soon as
37
+ the terminal is large enough. It follows a resize.
38
+
39
+ `--ascii` and `--help` are the only arguments. `--dir` and `--server` are
40
+ refused in this version: it reads no deployment yet.
41
+
42
+ ## Keys
43
+
44
+ | Key | Does |
45
+ |---|---|
46
+ | `?` | opens the help; `?` again closes it |
47
+ | `Esc` | closes the help |
48
+ | `q`, `Ctrl+C` | quits, with status 0 (a SIGINT from outside answers 130) |
49
+ | `Ctrl+Z` | suspends: the shell gets the terminal back as it was; `fg` returns and redraws |
50
+ | `Ctrl+L` | redraws the whole screen, and sets the terminal's modes again if something reset them |
51
+
52
+ The help screen is generated from the same table the program acts on, so it
53
+ always lists the keys that work. `Ctrl+\` does nothing. Pasted text is never
54
+ read as keys: a paste is dropped whole.
55
+
56
+ The mouse is never needed and never captured: your terminal's own selection
57
+ and scrolling keep working.
58
+
59
+ ## What it changes in your terminal, and restores
60
+
61
+ This is the complete list. On start, in this order:
62
+
63
+ 1. raw mode on the terminal (keys arrive unbuffered and unechoed);
64
+ 2. the alternate screen (`CSI ?1049h`), so your scrollback is untouched;
65
+ 3. the cursor hidden (`CSI ?25l`);
66
+ 4. autowrap off (`CSI ?7l`);
67
+ 5. bracketed paste on (`CSI ?2004h`).
68
+
69
+ On the way out, the reverse: bracketed paste off, autowrap on, the style
70
+ reset (`CSI 0m`), the cursor shown, the alternate screen left, raw mode off.
71
+
72
+ Two of these have a reason worth stating:
73
+
74
+ - **Autowrap is off** so that no row can wrap when your terminal and the
75
+ TUI's width table disagree about how wide a character is (some emoji and
76
+ some scripts). Each row is positioned on its own and erased to its end, so
77
+ a disagreement stays inside its row.
78
+ - **Bracketed paste is on** so that the terminal marks pasted text as a
79
+ paste, and the TUI can drop it instead of acting on it.
80
+
81
+ The terminal is restored after every way out that a process can handle:
82
+
83
+ | Way out | Exit status |
84
+ |---|---|
85
+ | `q` or `Ctrl+C` | 0 |
86
+ | an internal error (its message is printed after the alternate screen is left) | 1 |
87
+ | SIGINT | 130 |
88
+ | SIGTERM | 143 |
89
+ | SIGHUP, or the terminal going away | 129 |
90
+ | SIGQUIT | 131 |
91
+
92
+ A suspend (`Ctrl+Z`, or SIGTSTP from outside) restores the terminal in full
93
+ before the process stops, and sets the same modes again when it continues.
94
+ It stops the whole foreground process group, as a `Ctrl+Z` does for any
95
+ other program, so `oats tui` started through a wrapper (`sh -c`, `npx`)
96
+ suspends as one job.
97
+
98
+ `Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
99
+ a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
100
+ 130. A script that wraps `oats tui` meets that difference.
101
+
102
+ **SIGKILL cannot be handled.** No process can restore a terminal after
103
+ SIGKILL: the terminal is left in the alternate screen with the cursor hidden
104
+ and autowrap off. Run `reset`. Inside tmux also run `tput rmcup`: measured
105
+ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
106
+ stayed in the alternate screen until `tput rmcup`. Nothing else is left in
107
+ tmux: `oats tui` creates no session, window, option or key binding.
108
+
109
+ ## What it never does
110
+
111
+ - It switches on **no mouse reporting, no focus reporting, no keyboard
112
+ protocol, no keypad or cursor-key mode and no synchronized output**.
113
+ - It writes **no window title, no clipboard sequence, no bell**, and no query
114
+ that expects the terminal to reply.
115
+ - It uses **only your terminal's own sixteen colours** and bold, dim,
116
+ underline and reverse: no 256-colour or RGB value and no background fill,
117
+ so your theme stays the theme. With `NO_COLOR` set and not empty it uses no
118
+ colour at all. Nothing is told by colour alone.
119
+ - It draws its rules and marks in UTF-8 when `LC_ALL`, else `LC_CTYPE`, else
120
+ `LANG` names UTF-8, and in ASCII otherwise or with `--ascii`. No icon font,
121
+ no emoji. When the locale is not UTF-8, a character outside ASCII in text
122
+ it shows is drawn as `?`.
123
+ - It **never writes an escape byte to anything that is not a terminal**.
124
+ - It **never writes text it did not author straight to the terminal.** A
125
+ terminal acts on what is written to it, so every string from a kernel
126
+ answer, a repository, an agent or another machine passes one filter before
127
+ it is drawn: text holding a control character or a secret shape is shown
128
+ as `[withheld]`, and bidi controls, invisible characters and C1 controls
129
+ are replaced. The screen accepts only text that went through that filter
130
+ or the TUI's own words.
131
+ - It touches no tmux option, key binding, server or session, starts no
132
+ daemon, opens no socket and writes no file.
133
+
134
+ ## Errors
135
+
136
+ | Error | When | What to do |
137
+ |---|---|---|
138
+ | `E_NO_TERMINAL` | stdin or stdout is not a terminal, or `TERM` is unset, empty or `dumb`. One line on stderr, nothing on stdout, exit 1 | run it in a terminal; `oats status` prints the instances once |
139
+ | `E_BAD_ARGS` | `oats tui --json`: it is interactive and has no JSON form. The usual failure envelope, exit 1 | `oats status --json` is the machine view |
140
+ | `E_BAD_ARGS` | any argument other than `--ascii` and `--help`. One line on stderr with the usage, exit 1 | `oats tui --help` |
141
+
142
+ `E_NO_TERMINAL` appears only in that stderr line, never in a JSON envelope.
143
+
144
+ ## Where it has been run
145
+
146
+ So far `oats tui` has been run in tmux only: not in a terminal emulator
147
+ without tmux, and not over ssh.
148
+ The automated tests run the real `oats tui` in tmux (a pane is a real
149
+ terminal: keys and screen are bytes through a pty), on a private tmux server.
150
+ Other terminals and multiplexers are untested so far: that is a statement
151
+ about the tests, not a list of what is supported. If it misbehaves in yours,
152
+ that is a bug worth reporting, with the terminal's name and `TERM`.
@@ -54,8 +54,8 @@ 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.9.0 # bare version → resolves through the official catalog
58
- oats.okf: v5.0.0
57
+ oats.framework: v1.9.3 # bare version → resolves through the official catalog
58
+ oats.okf: v5.0.2
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone