@awebai/oats 0.52.0 → 0.54.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 (100) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +314 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
  6. package/docs/desktop-cli-api.md +696 -60
  7. package/docs/desktop-instance-start.md +25 -12
  8. package/docs/execution-targets.md +1 -0
  9. package/docs/implementation.md +184 -12
  10. package/docs/integrations.md +6 -3
  11. package/docs/knowledge.md +2 -2
  12. package/docs/macos-test-runs.md +246 -0
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +210 -6
  16. package/docs/release-notes/v0.53.0.md +1288 -0
  17. package/docs/release-notes/v0.54.0.md +142 -0
  18. package/docs/schedules.md +7 -1
  19. package/docs/souls-and-instances.md +239 -16
  20. package/docs/tui.md +453 -21
  21. package/docs/upgrading.md +310 -0
  22. package/docs/workspaces.md +123 -3
  23. package/lib/automations.mjs +22 -22
  24. package/lib/claim.mjs +93 -4
  25. package/lib/config-data.mjs +4 -1
  26. package/lib/core.mjs +569 -121
  27. package/lib/instance-events.mjs +19 -1
  28. package/lib/instance-git.mjs +39 -3
  29. package/lib/instance-inspect.mjs +5 -6
  30. package/lib/instance-lifecycle.mjs +145 -18
  31. package/lib/instance-resolution.mjs +59 -6
  32. package/lib/launch-preference.mjs +226 -15
  33. package/lib/local-edit.mjs +118 -0
  34. package/lib/packages.mjs +18 -5
  35. package/lib/pi-bridge.mjs +308 -0
  36. package/lib/refused-text.mjs +11 -0
  37. package/lib/remote.mjs +404 -60
  38. package/lib/resolve.mjs +2 -1
  39. package/lib/retained-after-retire.mjs +2 -2
  40. package/lib/retire-output.mjs +12 -1
  41. package/lib/schedule-host.mjs +6 -35
  42. package/lib/shell-word.mjs +13 -0
  43. package/lib/soul-launch-verbs.mjs +153 -0
  44. package/lib/stable-node.mjs +62 -0
  45. package/lib/teams-verbs.mjs +18 -46
  46. package/lib/workspace.mjs +75 -27
  47. package/package-catalog.json +4 -4
  48. package/package.json +2 -1
  49. package/packages/client/attach-exit.mjs +25 -0
  50. package/packages/client/cli-adapter.mjs +16 -3
  51. package/packages/client/cli-locator.mjs +2 -2
  52. package/packages/client/deployment-contract.mjs +4 -0
  53. package/packages/client/deployment-facts.mjs +71 -10
  54. package/packages/client/deployment-panel.mjs +49 -11
  55. package/packages/client/deployment-read-cli.mjs +7 -3
  56. package/packages/client/display-text.mjs +8 -2
  57. package/packages/client/instance-acts.mjs +46 -10
  58. package/packages/client/instance-events-contract.mjs +4 -2
  59. package/packages/client/instance-presentation.mjs +66 -2
  60. package/packages/client/instance-tree.mjs +23 -14
  61. package/packages/client/kernel-lines.mjs +31 -0
  62. package/packages/client/kernel-made.mjs +23 -0
  63. package/packages/client/launch-prompt-outcome.mjs +51 -16
  64. package/packages/client/lifecycle-contract.mjs +45 -4
  65. package/packages/client/liveness.mjs +14 -1
  66. package/packages/client/own-codes.mjs +31 -0
  67. package/packages/client/panel-views.mjs +18 -11
  68. package/packages/client/readiness-contract.mjs +3 -1
  69. package/packages/client/remote-address.mjs +34 -9
  70. package/packages/client/remote-identity-memory.mjs +94 -0
  71. package/packages/client/remote-roster.mjs +92 -6
  72. package/packages/client/session-attach.mjs +175 -0
  73. package/packages/client/spawn-apply-contract.mjs +16 -4
  74. package/packages/client/spawn-messages.mjs +26 -3
  75. package/packages/client/spawn-preview-cli.mjs +8 -2
  76. package/packages/client/spawn-preview-contract.mjs +5 -1
  77. package/packages/client/terminal-exec.mjs +21 -0
  78. package/packages/client/workspace-choices.mjs +95 -0
  79. package/packages/client/workspace-views.mjs +39 -3
  80. package/packages/record/README.md +21 -0
  81. package/packages/record/bin/setup.mjs +108 -15
  82. package/packages/tui/README.md +30 -12
  83. package/packages/tui/lib/actions.mjs +16 -1
  84. package/packages/tui/lib/client.mjs +32 -1
  85. package/packages/tui/lib/config.mjs +151 -0
  86. package/packages/tui/lib/main.mjs +117 -46
  87. package/packages/tui/lib/model.mjs +392 -0
  88. package/packages/tui/lib/read.mjs +473 -0
  89. package/packages/tui/lib/store.mjs +364 -0
  90. package/packages/tui/lib/term/keys.mjs +44 -0
  91. package/packages/tui/lib/term/screen.mjs +16 -4
  92. package/packages/tui/lib/term/text.mjs +60 -0
  93. package/packages/tui/lib/term/tty.mjs +13 -3
  94. package/packages/tui/lib/views/detail.mjs +46 -0
  95. package/packages/tui/lib/views/frame.mjs +230 -36
  96. package/packages/tui/lib/views/help.mjs +125 -13
  97. package/packages/tui/lib/views/instances.mjs +137 -0
  98. package/packages/tui/lib/views/scroll.mjs +19 -0
  99. package/packages/tui/lib/views/switcher.mjs +97 -0
  100. package/skills/oats-getting-started/SKILL.md +8 -2
@@ -548,6 +548,9 @@ Hooks receive:
548
548
  compatibility alias), `OATS_AGENT`, `OATS_SOUL`, `OATS_SOUL_ID`,
549
549
  `OATS_CONTEXT`, `OATS_WORKSPACE`, `OATS_ROOT`;
550
550
  - `OATS_CLI_BIN` (the running kernel's `bin/oats.mjs`);
551
+ - `OATS_NODE_BIN` (the node to write into anything that outlives the hook:
552
+ the node running the kernel, by a path that survives a Node upgrade,
553
+ [below](#the-node-a-hook-writes-down));
551
554
  - `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_META`;
552
555
  - the team and workspace variables of
553
556
  [Teams in the provider environment](#teams-in-the-provider-environment),
@@ -567,6 +570,8 @@ from the deployment directory) receives:
567
570
 
568
571
  - `OATS_CAPABILITY`;
569
572
  - `OATS_CLI_BIN`;
573
+ - `OATS_NODE_BIN`: the node to write into anything that outlives the command,
574
+ as hooks get it;
570
575
  - `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`: the home's recorded payload, or
571
576
  the soul's merged payload from the deployment;
572
577
  - the team and workspace variables, as hooks get them;
@@ -735,6 +740,47 @@ Spawn order is by capability name; retirement reverses successful
735
740
  spawn order. Hooks run from the instance's own copy
736
741
  (`<home>/.oats/modules/<cap>/`).
737
742
 
743
+ ### The node a hook writes down
744
+
745
+ A hook or a command that writes a `node` path into something that outlives it
746
+ (a harness's settings file, a unit, a script) writes `OATS_NODE_BIN`, never
747
+ its own `process.execPath`: on Homebrew that is the versioned keg
748
+ (`…/Cellar/node/<version>/bin/node`), which the next `brew upgrade node`
749
+ removes, and what was written then fails where nobody sees it. To run
750
+ something at once, `process.execPath` is still right.
751
+
752
+ `OATS_NODE_BIN` is the node running the kernel, the one that runs
753
+ `OATS_CLI_BIN`. A hook is itself run as the `node` first on its `PATH`, which
754
+ can be another one. The kernel computes the path once per process, by the one
755
+ rule it also uses for [the host timer's unit](schedules.md#the-host-timers-unit):
756
+
757
+ 1. the keg's `<prefix>/opt/<formula>/bin/node`, when that is the node running
758
+ the kernel;
759
+ 2. else the first `node` on the kernel's own `PATH` that is that same file.
760
+ Entries inside an instance home and inside a versioned keg are not looked
761
+ at;
762
+ 3. else the node's own path, as it is.
763
+
764
+ The second case answers only a `node` that is the same file as the one
765
+ running the kernel. A version manager's shim is another program, so it is
766
+ never the answer: which node a shim runs depends on the directory it is run
767
+ from. With mise the answer is the version's own install, which lasts until
768
+ that version is removed (measured: mise's shim puts that directory on the
769
+ `PATH` of what it starts). Other version managers were not measured.
770
+
771
+ In the third case a spawn and a start each carry one warning, for every
772
+ harness, that the node path is not stable; a preview carries none. The hook
773
+ itself cannot report it.
774
+
775
+ A package that also runs under a kernel older than the variable falls back to
776
+ `process.execPath` when `OATS_NODE_BIN` is absent or not an absolute path.
777
+
778
+ `oats setup` is given the same answer: the kernel sets `OATS_NODE_BIN` in its
779
+ own process, over any value the caller's environment held, before it runs the
780
+ turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
781
+ into the capture hooks and the capture watcher's unit. In the third case
782
+ `oats setup` carries the warning, a dry run included.
783
+
738
784
  ### The worktree event
739
785
 
740
786
  `OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
@@ -972,8 +1018,20 @@ clears it.
972
1018
  symlink or not a directory.
973
1019
  - **When it writes.** It writes at spawn, because `oats spawn` runs no
974
1020
  launch hook, and at every `oats session start|restart`, so the node and
975
- CLI paths it bakes in follow the current kernel. A launch preview writes
976
- nothing. Every pass answers `{}`: no launch arguments and no env. Codex
1021
+ CLI paths it bakes in follow the current kernel. The node is
1022
+ `OATS_NODE_BIN` ([the node a hook writes down](#the-node-a-hook-writes-down)):
1023
+ the kernel's own node, by a path that survives a Node upgrade. Under a
1024
+ kernel that does not set the variable it is the hook's own
1025
+ `process.execPath`, which on Homebrew is the versioned keg, gone at the
1026
+ next `brew upgrade node`. With mise the variable is the version's own
1027
+ path, as the hook's own node was (other version managers were not
1028
+ measured), and a start rewrites the hooks after the version changes. The
1029
+ hook a start runs is the copy of oats.core
1030
+ in the home (`.oats/modules/oats.core`), which a start does not refresh. A
1031
+ home spawned with an oats.core that does not read the variable therefore
1032
+ writes its hook's own node path at every start: a restart repairs its
1033
+ hooks after each Node upgrade, and a respawn gives it the lasting path. A
1034
+ launch preview writes nothing. Every pass answers `{}`: no launch arguments and no env. Codex
977
1035
  and pi homes get nothing.
978
1036
  - **It never hurts the session.** Claude Code reads a hook's stdout and exit
979
1037
  code as decisions. So every command runs the script through `/bin/sh`
@@ -1214,6 +1272,8 @@ passed as arguments; no shell is involved.
1214
1272
  - `OATS_CAPABILITY`, `OATS_SETTINGS` (the payload as JSON) and
1215
1273
  `OATS_SETTINGS_ORIGINS` (where each leaf came from, as hooks get it);
1216
1274
  - `OATS_CLI_BIN`;
1275
+ - `OATS_NODE_BIN` (the node to write into anything that outlives the check,
1276
+ as hooks get it);
1217
1277
  - `OATS_WORKSPACE` (the deployment);
1218
1278
  - the team variables `OATS_DEFAULT_TEAM`, `OATS_DEFAULT_TEAM_ID`,
1219
1279
  `OATS_DEFAULT_TEAM_FROM`, `OATS_TEAMS`, `OATS_TEAMS_SOURCE` (see
@@ -1388,8 +1448,10 @@ its own; the tick records what it folds.
1388
1448
  **Environment:** the one a `--soul` [readiness check](#readiness-check-bindingcheck)
1389
1449
  gets, for the trigger's soul: every ambient `OATS_*`, `OAS_*` and `PI_*`
1390
1450
  variable removed, the rest inherited, and the kernel's `OATS_CAPABILITY`,
1391
- `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_WORKSPACE`,
1392
- the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and `OATS_SOUL`. There is no
1451
+ `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_NODE_BIN`
1452
+ (the node to write into anything that outlives the run, as hooks get it),
1453
+ `OATS_WORKSPACE`, the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and
1454
+ `OATS_SOUL`. There is no
1393
1455
  `OATS_INSTANCE` or `OATS_INSTANCE_HOME`, and the kernel passes no credential.
1394
1456
  Under the host timer, the inherited environment is the timer's (only `PATH`
1395
1457
  and `OATS_HOME_DIR`): keep the source's login in its own store under `HOME`,
@@ -64,13 +64,13 @@ refused (`E_WORKSPACE_SCHEMA`).
64
64
  | `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
65
65
  | `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
66
66
  | `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
67
- | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
67
+ | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). |
68
68
  | `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
69
69
  | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
70
70
  | `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
71
71
  | `triggers.disabled`, `schedules.disabled` | Workspace triggers and schedules (`<member>/<id>`) this host does not run, without a commit. Written by `oats trigger disable` / `oats schedule disable`. |
72
72
  | `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. `default: true` makes it this host's baseline for its harness (0.32). See [Launch configurations](#launch-configurations). |
73
- | `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. See [Launch preferences](#launch-preferences). |
73
+ | `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. Written by `oats soul launch set\|remove` (0.53). See [Launch preferences](#launch-preferences). |
74
74
 
75
75
  Which teams a soul may join, and its default, are committed in the workspace's
76
76
  `souls:`, never here: `souls.teams` and `souls.default` were removed in 0.38.0
@@ -308,7 +308,8 @@ configuration is a host choice: a soul never names one.
308
308
  it.
309
309
  - `oats launch-config list` shows the effective entries;
310
310
  `oats launch-config set <name> --file <json>` and
311
- `oats launch-config remove <name>` rewrite only this block;
311
+ `oats launch-config remove <name>` rewrite only this block, under the
312
+ lock every kernel command that rewrites `oats-local.yaml` holds;
312
313
  `oats launch-config preview (--home <abs> | --soul <name>) --json` shows
313
314
  what a start would run (harness, model, executable, argv, redacted
314
315
  environment, command and preflight checks) and starts nothing.
@@ -389,6 +390,38 @@ souls:
389
390
  oats.engineering/code-reviewer: { harness: codex } # a package soul
390
391
  ```
391
392
 
393
+ - **Write `souls.launch` with `oats soul launch`** (0.53.0), not by hand:
394
+
395
+ ```
396
+ oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>])
397
+ oats soul launch remove <soul>|'*'|<exact key>
398
+ ```
399
+
400
+ each with `--plan` (every check, nothing written), `--dir <deployment>`
401
+ and `--json`.
402
+ - `set` names the soul as a spawn does and writes the key that soul has:
403
+ its bare name, or `<package>/<soul>` for a package's. So it cannot write
404
+ a key that names no soul. `'*'` is every soul without an entry of its
405
+ own. `--launch-config <name>` must be a launch configuration this file
406
+ declares (`none` is the bare harness); `--harness` writes the inline
407
+ preference.
408
+ - `remove` takes a soul, `'*'`, or the exact text of a key in the file.
409
+ The exact text is tried first and needs no read of the workspace, so a
410
+ key that names no soul can always be removed. An entry the file does not
411
+ have is refused (`E_LAUNCH_PREFERENCE_UNKNOWN`), never answered "done".
412
+ - Both answer what the next spawn of that soul selects, and every key of
413
+ `souls.launch` that still names no soul the workspace offers.
414
+ - **The file is rewritten, and every other entry keeps its value and its
415
+ comments.** The write holds the lock `oats teams` holds, so neither
416
+ drops the other's change.
417
+ - **A name two members offer.** A member's soul is keyed by its bare name,
418
+ so one entry pins every member's soul of that name: an entry cannot pin
419
+ one of them and leave the other. `oats soul launch set <member>/<soul>`
420
+ writes the bare name and lists each soul the entry applies to; the bare
421
+ name alone is refused, as for a spawn (`E_SOUL_AMBIGUOUS`). To run one
422
+ of them differently, name its launch on that spawn (`--launch-config` or
423
+ `--harness`), or keep the other off this machine (`souls.disabled` takes
424
+ `<member>/<soul>`).
392
425
  - **Precedence for a new launch:** `--launch-config` or `--harness`, then
393
426
  `souls.launch.<soul>`, then `souls.launch."*"`, then the soul's `launch:`,
394
427
  then `pi` with its defaults. `--model` alone keeps the deciding layer's
@@ -402,6 +435,36 @@ souls:
402
435
  (`E_LAUNCH_CONFIG_AMBIGUOUS`). A preference without `model` uses the
403
436
  harness default's model, else the harness's own; it never borrows a lower
404
437
  layer's.
438
+ - **A key that names no soul refuses the launches it might have pinned**
439
+ (0.53). While `souls.launch` holds a key, other than `"*"`, that is the key
440
+ of no soul the workspace offers, a new launch that names no launch, of a
441
+ soul with no entry of its own, is refused
442
+ (`E_LAUNCH_PREFERENCE_UNMATCHED`). `souls.launch."*"`, the soul's `launch:`
443
+ or the host default would have decided that launch, and the kernel cannot
444
+ tell which soul the key was meant to pin. Before 0.53 the key was never
445
+ read, and the soul it was written for ran on the fall-through.
446
+ - **Refused:** `oats spawn`, preview and apply, and `oats session
447
+ start|restart --reselect-launch`, before anything is created, stopped or
448
+ started. `--model` alone names no launch.
449
+ - **Goes on:** a soul with its own entry; a launch named with
450
+ `--launch-config` or `--harness`; a plain start or restart of an
451
+ existing home, which selects nothing again.
452
+ - **The remedy, in this order:** pin the soul the key was meant for (`oats
453
+ soul launch set <soul> --launch-config <name>`, or `--harness <h>`),
454
+ then remove the key (`oats soul launch remove <key>`). Removing first
455
+ ends the refusal and leaves that soul on the fall-through. The refusal
456
+ names the keys and, for each, the nearest soul keys.
457
+ - **Where it shows:** `oats souls` and `oats inspect --soul` carry it on
458
+ each soul a spawn would refuse and list each such key; `oats doctor`
459
+ lists each key with the command that removes it, from this machine's
460
+ last read of the souls.
461
+ - **A key the kernel could not check refuses nothing:** a bare key while a
462
+ member is not confirmed or a member's or an external soul failed to
463
+ read, a `<package>/…` key while that package is declared and not locked
464
+ or one of its souls failed to read, and every key in the standalone view
465
+ of a workspace whose host cannot be read. `oats doctor` says so
466
+ (`launch-preference-unchecked`). The key of a soul listed in
467
+ `souls.disabled` matches that soul. `"*"` is never reported.
405
468
  - **A missing harness is refused**, never replaced: `E_HARNESS_UNAVAILABLE`
406
469
  names the layer that chose it and the fix (install the harness, or override
407
470
  it here in `souls.launch`). `oats souls` still lists the soul, with the
@@ -62,6 +62,9 @@ symlink enters as `symlink:<target>`; empty directories and a top-level `.git/`
62
62
  The cache may be wiped at any time. Operations on one cache repo are serialized.
63
63
  - Failures: `E_REMOTE_UNREADABLE { url, key, reason }`, `reason` ∈ `auth`, `not-found`, `network`,
64
64
  `timeout`, `unknown`. Nothing half-succeeds.
65
+ - Reference-bearing diagnostics use `redactUrl`, including parser refusals, package and
66
+ workspace validation errors, and quoted Git text; the [display rule](../workspaces.md#repository-references-in-diagnostics)
67
+ removes user information without changing the reference used for transport.
65
68
 
66
69
  ---
67
70