@awebai/oats 0.69.14 → 0.69.15

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 (49) hide show
  1. package/bin/oats.mjs +79 -18
  2. package/docs/capabilities.md +54 -12
  3. package/docs/container.md +57 -12
  4. package/docs/desktop-cli-api.md +215 -19
  5. package/docs/execution-targets.md +15 -3
  6. package/docs/first-team.md +4 -3
  7. package/docs/implementation.md +18 -8
  8. package/docs/release-notes/v0.69.15.md +444 -0
  9. package/docs/schedules.md +133 -2
  10. package/docs/servers.md +60 -2
  11. package/docs/souls-and-instances.md +87 -7
  12. package/docs/upgrading.md +17 -5
  13. package/lib/claim.mjs +2 -3
  14. package/lib/command-flags.mjs +4 -2
  15. package/lib/core.mjs +215 -72
  16. package/lib/dir-lock.mjs +17 -0
  17. package/lib/errors.mjs +2 -1
  18. package/lib/host-run.mjs +218 -0
  19. package/lib/host-stop-child.mjs +21 -0
  20. package/lib/instance-git.mjs +32 -6
  21. package/lib/instance-lifecycle.mjs +4 -3
  22. package/lib/instance-listing.mjs +35 -6
  23. package/lib/kernel-features.mjs +4 -1
  24. package/lib/read-call.mjs +1 -1
  25. package/lib/remote.mjs +17 -14
  26. package/lib/schedule.mjs +237 -20
  27. package/lib/servers.mjs +83 -5
  28. package/lib/session-end.mjs +28 -8
  29. package/lib/session-resume.mjs +10 -18
  30. package/lib/session-seen.mjs +4 -64
  31. package/lib/status-words.mjs +11 -4
  32. package/lib/system-tools.mjs +1 -36
  33. package/lib/worktree-hooks.mjs +6 -175
  34. package/lib/worktree.mjs +19 -10
  35. package/package.json +4 -1
  36. package/packages/record/README.md +56 -21
  37. package/packages/record/docs/capture-service.md +8 -5
  38. package/packages/record/docs/turn-record-sot.md +9 -0
  39. package/packages/record/lib/capture-health.mjs +6 -4
  40. package/packages/record/lib/capture-lock.mjs +31 -27
  41. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  42. package/packages/record/lib/capture-scratch.mjs +2 -1
  43. package/packages/record/lib/derived-state.mjs +4 -2
  44. package/packages/record/lib/index-db.mjs +4 -2
  45. package/packages/record/lib/lock-holder.mjs +21 -0
  46. package/packages/record/lib/private-files.mjs +18 -0
  47. package/packages/record/lib/process-identity.mjs +310 -0
  48. package/packages/record/lib/store.mjs +31 -25
  49. package/skills/oats-getting-started/SKILL.md +1 -1
package/docs/servers.md CHANGED
@@ -425,7 +425,9 @@ Every routed ssh call carries these options, before `--` and the host:
425
425
  failed: …`). When ssh never started on this machine, the `--json` envelope
426
426
  says so with `error.details: {"sshStarted": false}`; without details, ssh
427
427
  ran and the link failed
428
- ([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)).
428
+ ([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)). A link that
429
+ fails under a routed spawn carries the decision and the key to run it
430
+ again with ([Run there](#run-there)).
429
431
 
430
432
  ## Run there
431
433
 
@@ -440,9 +442,27 @@ Arguments are quoted for the remote shell. Local files (`--task-file`,
440
442
  `--wake-file`, a schedule or launch-configuration `--file`) are read here and
441
443
  sent as text or on stdin, never as paths.
442
444
 
445
+ <a id="a-routed-spawns-task"></a>
446
+ **A routed spawn's task is on no command line, for a server that advertises
447
+ `spawn-task-stdin`.** The text of `--task` or of `--task-file` goes to such a
448
+ server on the standard input of the ssh session, to the server's preview and
449
+ to its spawn alike, and the remote command carries `--task-file -` in its
450
+ place: the text is in the arguments of neither the local `ssh` process nor
451
+ the server's `oats`, where every user of either machine could read it in the
452
+ process list. A server that does not advertise `spawn-task-stdin` cannot read
453
+ it there, and gets it as an argument of the remote command: the spawn
454
+ succeeds, the task is readable in both process lists while it runs (this
455
+ machine's, in the `ssh` command, and the server's), and the answer carries
456
+ one warning that says so: `remote oats <version> at <host> does not
457
+ advertise spawn-task-stdin, so the task was passed as an argument, visible
458
+ in this machine's process list (the ssh command) and the host's while the
459
+ spawn runs; upgrade the host`. Upgrade OATS on the server to keep tasks off
460
+ both command lines. A `--wake-message` and a
461
+ schedule's spec still travel as arguments.
462
+
443
463
  | Command | Where it runs | The server must advertise |
444
464
  |---|---|---|
445
- | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
465
+ | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-task-stdin` for a `--task` or `--task-file` kept off the command line (without it: the task as an argument, and a warning; [a routed spawn's task](#a-routed-spawns-task)); `spawn-preview-2` for `--preview`; `spawn-preview-2`, `spawn-apply-2` and `spawn-idempotency-2` for a spawn bound to its preview and a key (without them: one call and a warning); `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
446
466
  | `status` | registered workspace | |
447
467
  | `retire` | the instance's home | `retire-home` to retire by exact home |
448
468
  | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key`; `session-attach-no-status-line` for `attach --no-status-line`, which a host without it ignores |
@@ -472,6 +492,44 @@ checked against the harness it would use (the flag, or the soul's default as
472
492
  the remote roster reports it). A host that advertises no harness list is
473
493
  assumed to run only pi and claude, on tmux, with no launch options.
474
494
 
495
+ **A routed spawn.** `oats spawn <soul> --server <id>` runs the spawn's checks
496
+ here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and options), then
497
+ asks the server's kernel in two calls:
498
+
499
+ 1. its preview (`spawn … --preview`), which decides the name and everything
500
+ else and creates nothing;
501
+ 2. the spawn itself, bound to that decision and to a key made for this
502
+ request (`--expect-decision <revision> --idempotency-key <key>`).
503
+
504
+ The answer is the server's keyed answer (`decision`, `replayed`, `wake`
505
+ beside the rest) plus `server`, `target` and `snapshot`, and the route is
506
+ saved. With `--suggest-name` the preview chooses the name and the spawn
507
+ carries it as `--name`; the answer keeps the preview's `naming`. This needs
508
+ the server's `spawn-suggest-name` and `spawn-name` too.
509
+
510
+ - **A link that fails under the second call** (a lost connection, a
511
+ timeout) is `E_SSH`, and the server may have started the spawn. The
512
+ message ends with the fix, and `--json` carries it:
513
+ `error.details: {decision, idempotencyKey, fix}`. Run the same spawn again
514
+ with `--expect-decision <decision.revision> --idempotency-key
515
+ <idempotencyKey>` (and `--name <decision.instance>` in place of
516
+ `--suggest-name`): the server answers the instance the first attempt
517
+ created (`replayed: true`), or creates it, and the route is saved. An
518
+ attempt still running there answers `E_SPAWN_INCOMPLETE`, naming the
519
+ instance. Run again without the two flags, the spawn is a separate request
520
+ and may create a second instance.
521
+ - **A name taken between the two calls** (another spawn on the server took
522
+ it) is `E_DECISION_STALE`; nothing was created. Run the spawn again.
523
+ - **A spawn that brings `--expect-decision` or `--idempotency-key`** travels
524
+ as given, in one call: the caller previewed (`--server <id> --preview`) and
525
+ holds the key.
526
+ - **A server that does not advertise `spawn-preview-2`, `spawn-apply-2` and
527
+ `spawn-idempotency-2`** gets the spawn in one call, as given, and the
528
+ answer carries a warning: if the link drops while it spawns, the spawn
529
+ cannot be retried safely, since the instance may exist there and a second
530
+ run would create another. Check `oats status --server <id>` before running
531
+ it again, or upgrade OATS there.
532
+
475
533
  **A routed preview.** `oats spawn <soul> --server <id> --preview` runs the
476
534
  spawn's checks here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and
477
535
  options), then asks the server's kernel for its preview. It prints the local
@@ -533,6 +533,16 @@ takes a final capture of notes and the session record into durable custody; an
533
533
  incomplete capture keeps the home for a retry. Retirement never waits for a
534
534
  model or GitHub: processing continues after the home is gone.
535
535
 
536
+ A spawn that is killed after its spawn hooks started and before it wrote the
537
+ home's record (SIGKILL, a container stop, a dropped connection) leaves a home
538
+ `oats retire` still cleans up: the spawn records, before its first spawn hook,
539
+ which retire hooks a retire must run, and the retire runs them before it
540
+ removes the home. A home whose record does not say which retire hooks to run,
541
+ and that has no such marker, is refused with `E_UNIDENTIFIED_INSTANCE_HOME`
542
+ and kept; `--force` removes it without running a hook, once what its
543
+ capabilities registered is cleaned up by hand
544
+ ([A spawn in progress](capabilities.md#manifest)).
545
+
536
546
  A retire hook's warning, such as an action someone must still take, is in the
537
547
  retire's `warnings` and stays readable after the home is gone: each one is a
538
548
  `retire-warning` event in the instance's workspace log, read with
@@ -743,8 +753,9 @@ way.
743
753
  failed: the retire refuses with `E_WORK_INSPECTION_FAILED` at its first
744
754
  inspection, as for any [status that fails](#retire-status-fails), with
745
755
  `--discard-worktree` and `--force` too. A spawn into a worktree of such a
746
- repository is refused the same way and rolled back. Remove or rename the
747
- driver in the repository's configuration, then retry.
756
+ repository is refused with the same code before its checkout and rolled
757
+ back ([a checkout runs no filter driver](#checkout-filter-drivers)). Remove
758
+ or rename the driver in the repository's configuration, then retry.
748
759
  - A driver that the operator's global or system configuration defines is
749
760
  the operator's own and runs with the operator's command, in the worktree
750
761
  and in the recovery alike. That holds when the repository's configuration
@@ -752,7 +763,10 @@ way.
752
763
  `git lfs install`): the repository's values for it are replaced by the
753
764
  operator's, so a command the repository gives that name never runs. The
754
765
  operator's configuration is the human's; the repository's is the agent's
755
- to write.
766
+ to write. One case runs neither: the repository defines `process` for that
767
+ name and the operator's configuration does not. Git has no way to unset a
768
+ variable on its command line, and a `process` set to nothing turns the
769
+ driver's `clean` and `smudge` off with it, so the file is read unfiltered.
756
770
  - The recovery has no local configuration, so it has none of the
757
771
  repository's drivers. Its status must still be the worktree's, and for a
758
772
  file such a filter applies to it can differ: the worktree reads an
@@ -1303,9 +1317,12 @@ leaves what happened on disk (OATS 0.53.0):
1303
1317
  - **Its pending marker, only when the home is owed a retire:** when a retire
1304
1318
  hook was started or the removal of the home began. The usual quarantine
1305
1319
  marker is there too when hooks reported incomplete cleanup. The instance
1306
- then reads as retiring: `oats instance stop --apply` and `oats session
1307
- start` answer `E_INSTANCE_RETIRING`, and `oats retire <instance>`
1308
- continues. In every other case the completion removes its marker.
1320
+ is then owed a retire: `oats session start` answers
1321
+ `E_INSTANCE_RETIRING`, and `oats retire <instance>` continues. `oats
1322
+ instance stop --apply` is not refused: the completion has ended, so
1323
+ nothing holds the home against a stop
1324
+ ([a completion that was killed](#self-retire-interrupted)). In every
1325
+ other case the completion removes its marker.
1309
1326
  Nothing of the home was changed, so the instance is a stopped or a
1310
1327
  running instance like any other: a start works, and a wake schedule may
1311
1328
  start it. A session or a child that the completion stopped on its way
@@ -1313,6 +1330,29 @@ leaves what happened on disk (OATS 0.53.0):
1313
1330
  - **One event,** `retire-refused`, which says which of the two it was
1314
1331
  ([Events](desktop-cli-api.md#retire-refused-event)).
1315
1332
 
1333
+ <a id="self-retire-interrupted"></a>**A completion that was killed** (a
1334
+ `SIGKILL`, a container that stopped, a reboot) leaves no outcome, and its
1335
+ pending marker stays. The marker names the completion by its pid, its start
1336
+ and its boot, and the rule is: a pending marker holds its home only while
1337
+ the completion it names can still act; once that completion is gone,
1338
+ `oats retire <instance>` takes the retire over and completes it,
1339
+ `oats session start` is refused with that command in its message, and a
1340
+ stop is not refused: `oats instance stop --apply`, the stop a retire makes
1341
+ of a recorded child, and the stop `oats host run` makes of every running
1342
+ home when the host stops all stop a session that still runs there, and the
1343
+ marker stays. A
1344
+ completion is gone when its process has ended, when its pid runs with
1345
+ another start, and when the marker was written in another boot, whatever
1346
+ its pid reads as there. `oats status` shows the row's `retire` as
1347
+ `interrupted`, and `oats doctor` lists the home. A start answers
1348
+ `E_INSTANCE_RETIRING`, `<instance> is owed a retire (its retire was
1349
+ interrupted): finish it with` and the retire to run, because the home is
1350
+ never started again: the completion may have run retire hooks before it
1351
+ was killed, and a start would bring back an instance whose identity is
1352
+ gone. A marker that names no completion (one an OATS before 0.51.0 wrote)
1353
+ refuses a start and a stop as before, since whether its retire runs cannot
1354
+ be told, and `oats retire <instance>` completes it.
1355
+
1316
1356
  <a id="self-retire-hook-retry"></a>**A completion retries a cleanup that only
1317
1357
  retire hooks left incomplete** (oats-project/oats#1747), because a provider's
1318
1358
  failure is often transient. When the retire ends with the home quarantined,
@@ -1836,6 +1876,41 @@ a `--repo` that is not a clone of the soul's repository starts at its `HEAD`.
1836
1876
  The spawn result and `instance.json` record the start point as
1837
1877
  `base: {ref, oid}`.
1838
1878
 
1879
+ <a id="checkout-filter-drivers"></a>
1880
+ **A checkout runs no filter driver of the repository.** Every Git command
1881
+ OATS runs that writes a tree's files (the spawn's `git worktree add` here,
1882
+ and the `git worktree add` and `git switch` of
1883
+ [`oats worktree add`](#extra-trees)) runs with every filter driver the
1884
+ repository's own configuration defines overridden to no command, so a
1885
+ `filter.<name>.smudge` or `.process` command that configuration names is
1886
+ never run and a file carrying the `filter` attribute is written as its
1887
+ committed bytes. The read of the configuration, the override and their
1888
+ limits are [a retire's](#retire-filter-drivers).
1889
+
1890
+ - A driver that the operator's global or system configuration defines is
1891
+ the operator's own and runs. Git LFS set up with `git lfs install` is one:
1892
+ its files are checked out as before. A driver of that name in the
1893
+ repository's configuration is replaced by the operator's values.
1894
+ - A driver only the repository's configuration defines does not run. With
1895
+ Git LFS set up by `git lfs install --local` alone, a tree OATS checks out
1896
+ holds the pointer files, not their content: run `git lfs install` for the
1897
+ operator, or `git lfs pull` in the tree.
1898
+ - A driver whose name cannot be passed on Git's command line (it holds `=`
1899
+ or is not UTF-8) cannot be overridden, so Git is not run: the spawn is
1900
+ refused with `E_WORK_INSPECTION_FAILED` and rolled back, and
1901
+ `oats worktree add` with `E_GIT_FAILED`, its tree removed.
1902
+
1903
+ <a id="no-file-monitor"></a>
1904
+ **No file monitor.** Every Git command OATS runs that reads or writes a work
1905
+ tree's files or its index runs with `core.fsmonitor=false`, so a file
1906
+ monitor command the repository's configuration names is never run: these
1907
+ checkouts and the fetch of `oats worktree add` between its two,
1908
+ `oats worktree remove`, a retire and its recovery copy, the status a spawn's
1909
+ baseline is taken from, the reads of `oats instance git` and
1910
+ `oats instance diff`, and the check `oats package add|remove` makes that
1911
+ `oats-workspace.yaml` is tracked in the checkout that holds it. The clone's Git hooks (`post-checkout` among them) are not part of
1912
+ this: they run in a checkout as they do for the operator's own Git.
1913
+
1839
1914
  After the spawn hooks succeed, the spawn fires the
1840
1915
  [`worktree` event](capabilities.md#the-worktree-event) for `work/`: the
1841
1916
  `worktree` hook of each capability the soul composes runs once, with `work/`
@@ -2033,6 +2108,10 @@ git -C <home>/.work-<p> fetch --refmap= origin <base>
2033
2108
  git -C <home>/.work-<p> switch -c <branch> <the fetched commit>
2034
2109
  ```
2035
2110
 
2111
+ - Neither checkout (`worktree add`, `switch`) runs a filter driver the
2112
+ repository's configuration defines: the files are written as their
2113
+ committed bytes ([a checkout runs no filter
2114
+ driver](#checkout-filter-drivers)).
2036
2115
  - The tree starts from the remote's current state, never from a local branch
2037
2116
  of the clone, which may be stale. A fetch that fails is
2038
2117
  `E_REMOTE_UNREADABLE`; a HEAD that is not the fetched commit is
@@ -2120,7 +2199,8 @@ owner read, write and search access, and keeps `.git` until all other entries
2120
2199
  are deleted, so a failed deletion can be retried.
2121
2200
  An unreadable branch or a failed inspection keeps the tree and record.
2122
2201
 
2123
- `remove` runs no filter driver the repository's configuration defines
2202
+ `remove` runs no file monitor the repository's configuration names
2203
+ ([no file monitor](#no-file-monitor)), and no filter driver it defines
2124
2204
  (`filter.<name>.clean`, `.process`): its own status of the tree, the clean
2125
2205
  check inside `git worktree remove` and the comparison of an unregistered
2126
2206
  tree's surviving files are each preceded by one read of that configuration,
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.14** ([release notes](release-notes/v0.69.14.md)).
10
- The 0.69.14 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.15** ([release notes](release-notes/v0.69.15.md)).
10
+ The 0.69.15 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.14,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.15,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.14 first
23
- npm install -g @awebai/oats@0.69.14 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.15 first
23
+ npm install -g @awebai/oats@0.69.15 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -204,6 +204,10 @@ of the Desktop and the CLI, and an optional package pin. A change a script
204
204
  must follow is in its release's Upgrade section whether or not it is listed
205
205
  here.
206
206
 
207
+ - **[0.69.15](release-notes/v0.69.15.md#upgrade):** Node 22.5.0 or later
208
+ before the CLI; on a shared host, `chmod -R go-rwx` each turn-record root;
209
+ a record root is written from one machine at a time; release a schedule
210
+ slot an earlier OATS left without its record (`oats doctor` lists it).
207
211
  - **[0.69.14](release-notes/v0.69.14.md#upgrade):** 0.69.13 was tagged but
208
212
  never published, so its steps (below) are this release's; the remaining
209
213
  state-changing commands refuse a flag they do not define.
@@ -571,6 +575,14 @@ an upgrade that is a lock directory left by the earlier OATS
571
575
  `oats` is running on the machine
572
576
  ([The sweep](execution-targets.md#the-sweep)).
573
577
 
578
+ `oats doctor` reports a schedule slot whose record cannot be read as a
579
+ `schedule-slot-unreadable` problem, naming the deployment, the job and the
580
+ remedy. After an upgrade that is a slot directory an earlier OATS left
581
+ without its `owner.json`. The tick reports that job invalid and runs the
582
+ deployment's other jobs. Check `oats schedule show <id>`; once its last run
583
+ is not running, `oats schedule reconcile <id> --clear` releases the slot
584
+ ([Schedules](schedules.md#files)).
585
+
574
586
  ## After a change of Node version
575
587
 
576
588
  Two paths are written into things that outlive a command: the kernel's, and
package/lib/claim.mjs CHANGED
@@ -241,9 +241,8 @@ export function claimUnheld(path, opts, otherwise) {
241
241
 
242
242
  /** Whether the holder a claim record names can still act, as processLiveness answers it, for the
243
243
  * caller whose refusals are `opts`: gone when its `holderGone` says so, whatever the process reads
244
- * as. The one reading of a holder for taking a claim (takeClaim) and for reading one (claimUnheld),
245
- * and of a cache write lock's holder that names its boot and start (lib/remote.mjs isStaleLock). */
246
- export function holderLiveness(holder, opts) {
244
+ * as. The one reading of a holder for taking a claim (takeClaim) and for reading one (claimUnheld). */
245
+ function holderLiveness(holder, opts) {
247
246
  return opts.holderGone?.(holder) ? { state: "gone" } : processLiveness(holder);
248
247
  }
249
248
 
@@ -12,6 +12,7 @@ export const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--jso
12
12
  export const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
13
13
  export const TEAMS_USAGE = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
14
14
  export const SOUL_LAUNCH_USAGE = "oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json] | oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]";
15
+ export const HOST_RUN_USAGE = "usage: oats host run [--stop-grace <seconds>] [--plan] [--json]";
15
16
  export const WORKTREE_USAGE = "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json] | oats worktree remove --purpose <p> [--json]";
16
17
 
17
18
  const WORKTREE_REFUSED = Object.freeze({
@@ -136,9 +137,10 @@ export const COMMAND_FLAGS = Object.freeze([
136
137
  schedule("disable"),
137
138
  schedule("reconcile", ["--clear"]),
138
139
  { command: "schedule tick", operands: [], values: SCHEDULE_VALUES, switches: ["--dry-run", "--host", "--json"], usage: "usage: oats schedule tick [--dry-run] [--host] [--dir <workspace> | --server <id>] [--json]" },
139
- { command: "schedule host install", operands: [], values: ["--max-concurrent", "--triggers-max-concurrent", "--os", ...SCHEDULE_VALUES], switches: ["--print", "--json"],
140
- usage: "usage: oats schedule host install [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | --print [--os darwin|linux] [--dir <workspace> | --server <id>] [--json]" },
140
+ { command: "schedule host install", operands: [], values: ["--max-concurrent", "--triggers-max-concurrent", "--os", ...SCHEDULE_VALUES], switches: ["--register-only", "--print", "--json"],
141
+ usage: "usage: oats schedule host install [--register-only] [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | --print [--os darwin|linux] [--dir <workspace> | --server <id>] [--json]" },
141
142
  { command: "schedule host uninstall", operands: [], values: SCHEDULE_VALUES, switches: ["--json"], usage: "usage: oats schedule host uninstall [--dir <workspace> | --server <id>] [--json]" },
143
+ { command: "host run", operands: [], values: ["--stop-grace"], switches: ["--plan", "--json"], usage: HOST_RUN_USAGE },
142
144
  { command: "trigger add", operands: [], values: ["--file", "--from", "--set", "--id", "--description", "--workspace", "--runs-on", "--owner", "--dir"], switches: ["--json"],
143
145
  usage: "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] [--dir <deployment>] [--json]" },
144
146
  { command: "trigger poll", operands: ["id"], values: ["--dir", "--max-age"], switches: TRIGGER_RUN_SOURCE, usage: "usage: oats trigger poll <id> --run-source [--max-age <s>] [--dir <deployment>] [--json]" },