@awebai/oats 0.51.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.
- package/README.md +1 -0
- package/bin/oats.mjs +109 -37
- package/docs/capabilities.md +9 -2
- package/docs/configuration.md +134 -88
- package/docs/desktop-cli-api.md +927 -92
- package/docs/desktop-instance-start.md +56 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +144 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +66 -9
- package/docs/integrations.md +9 -8
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +15 -5
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/schedules.md +91 -4
- package/docs/souls-and-instances.md +95 -25
- package/docs/tui.md +152 -0
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +186 -46
- package/lib/core.mjs +730 -185
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-inspect.mjs +40 -11
- package/lib/instance-lifecycle.mjs +169 -47
- package/lib/launch-preference.mjs +16 -0
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/schedule-host.mjs +154 -22
- package/lib/schedule.mjs +73 -24
- package/lib/system-tools.mjs +39 -0
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +5 -11
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +3 -3
- package/package.json +7 -2
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +548 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +68 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +34 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +142 -0
- package/packages/client/deployment-read-cli.mjs +53 -0
- package/packages/client/display-text.mjs +44 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +54 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +74 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +22 -0
- package/packages/client/instance-tree.mjs +453 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +165 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +372 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +35 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +286 -0
- package/packages/client/readiness-contract.mjs +172 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +126 -0
- package/packages/client/remote-roster.mjs +67 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +183 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +119 -0
- package/packages/client/spawn-preview-cli.mjs +32 -0
- package/packages/client/spawn-preview-contract.mjs +314 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +147 -0
- package/packages/tui/README.md +46 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +29 -0
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/main.mjs +105 -0
- package/packages/tui/lib/term/keys.mjs +323 -0
- package/packages/tui/lib/term/screen.mjs +122 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +49 -0
- package/packages/tui/lib/term/tty.mjs +168 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/frame.mjs +62 -0
- package/packages/tui/lib/views/help.mjs +28 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +29 -22
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- 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`
|
|
25
|
-
evaluates only the
|
|
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
|
|
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
|
|
@@ -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
|
|
222
|
-
`oats harness trust --dir D --
|
|
223
|
-
|
|
224
|
-
|
|
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
|
|
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
|
|
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
|
|
243
|
-
`--json` `warnings`):
|
|
244
|
-
|
|
245
|
-
|
|
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
|
-
|
|
248
|
-
does not cover folder-trust prompts
|
|
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).
|
|
@@ -447,21 +454,46 @@ scheduled it to release the claim. A self-retire that is scheduled counts from t
|
|
|
447
454
|
while its completion lives. A retire killed while it holds the claim leaves
|
|
448
455
|
the file behind until that name is retired again: the next retire takes the
|
|
449
456
|
claim over, because its holder is verifiably gone, and the file is safe to
|
|
450
|
-
remove by hand once its pid is gone.
|
|
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
|
|
451
459
|
retire left running: one of its retire hooks may still be running when the
|
|
452
460
|
next retire takes the claim over and runs the hooks again (#865). A holder whose start time cannot be
|
|
453
461
|
read is never taken for gone; the refusal names the pid, the file and the
|
|
454
|
-
way out.
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
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).
|
|
458
486
|
|
|
459
487
|
Recorded children (the instances whose recorded parent chain reaches this
|
|
460
488
|
one) are stopped first, never escalated, and kept: their homes stay. If one is
|
|
461
489
|
still running after the grace, or its stop cannot be established, retire
|
|
462
490
|
refuses with `E_CHILDREN_RUNNING` and retires nothing; `--force` does not
|
|
463
491
|
bypass it. This holds for plain, guarded and `--self` retires alike
|
|
464
|
-
([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.
|
|
465
497
|
|
|
466
498
|
Before any retire hook runs, retire preserves the instance's uncommitted and
|
|
467
499
|
unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
|
|
@@ -818,6 +850,40 @@ a file over 2 GiB it gives the size, and `find <work> -type f -size
|
|
|
818
850
|
or make it readable, then run `oats retire <instance>` again. With nothing to
|
|
819
851
|
preserve, the files are not read and the retire goes through.
|
|
820
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
|
+
|
|
821
887
|
The home is not copied again because the work is, and the work is not copied
|
|
822
888
|
again because the home is. The home's comparison after the hooks holds every
|
|
823
889
|
entry the home copy carries, as its bytes and permission bits, the kernel's
|
|
@@ -1114,10 +1180,11 @@ the new path.
|
|
|
1114
1180
|
with each, and they are part of the plan's revision: a tree created, removed,
|
|
1115
1181
|
dirtied or cleaned between the plan and a guarded apply, or a new target for
|
|
1116
1182
|
it, refuses the apply with `E_PLAN_STALE` before anything runs. The retire
|
|
1117
|
-
checks the trees again at the step itself and refuses with
|
|
1118
|
-
keeping the home, rather than move or remove a
|
|
1119
|
-
not say. The retire hooks have run by then, and
|
|
1120
|
-
removed
|
|
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
|
|
1121
1188
|
[the CLI API](desktop-cli-api.md#retire).
|
|
1122
1189
|
|
|
1123
1190
|
#### After a retire: inspect, restore, dispose
|
|
@@ -1442,7 +1509,8 @@ and hooks, and fetches and writes nothing.
|
|
|
1442
1509
|
A process is "still running" when its pid runs with the recorded start
|
|
1443
1510
|
time. It counts as gone only when its pid does not run (the operating
|
|
1444
1511
|
system says no such process: `kill -0` fails with ESRCH), or runs with another
|
|
1445
|
-
start
|
|
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
|
|
1446
1514
|
process is never taken for gone. `add` and `remove` refuse with
|
|
1447
1515
|
`E_LIFECYCLE_BUSY`, naming the pid and the exact file to remove by hand once
|
|
1448
1516
|
you have checked it: the record `.oats/trees/<p>.json`, or the claim
|
|
@@ -1463,7 +1531,9 @@ A claim left by a command that was killed is taken over by the next one,
|
|
|
1463
1531
|
once its holder (pid and start time) is verified gone. Any git step the
|
|
1464
1532
|
killed command left running is ended first, so it cannot finish late on
|
|
1465
1533
|
the new tree. A quarantined
|
|
1466
|
-
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).
|
|
1467
1537
|
|
|
1468
1538
|
**`remove`** runs `git worktree remove` (without `--force`) and `git worktree
|
|
1469
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`.
|
package/docs/workspaces.md
CHANGED
|
@@ -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.
|
|
58
|
-
oats.okf: v5.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
|