@awebai/oats 0.65.0 → 0.66.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 (36) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +8 -7
  3. package/docs/desktop-cli-api.md +5 -4
  4. package/docs/implementation.md +10 -1
  5. package/docs/integrations.md +1 -1
  6. package/docs/official-catalog.md +2 -2
  7. package/docs/packages.md +7 -7
  8. package/docs/release-notes/v0.66.0.md +183 -0
  9. package/docs/servers.md +2 -2
  10. package/docs/tui.md +137 -16
  11. package/docs/upgrading.md +1 -1
  12. package/docs/workspaces.md +9 -2
  13. package/lib/deployments.mjs +21 -5
  14. package/package-catalog.json +2 -2
  15. package/package.json +1 -1
  16. package/packages/client/cli-locator.mjs +2 -2
  17. package/packages/client/keymap.mjs +36 -9
  18. package/packages/client/machine-contract.mjs +1 -5
  19. package/packages/record/bin/setup.mjs +10 -2
  20. package/packages/record/docs/capture-service.md +45 -6
  21. package/packages/record/lib/capture-service-install.mjs +6 -95
  22. package/packages/record/lib/capture-setup-write.mjs +233 -0
  23. package/packages/tui/README.md +7 -6
  24. package/packages/tui/lib/actions.mjs +65 -64
  25. package/packages/tui/lib/client.mjs +1 -0
  26. package/packages/tui/lib/config.mjs +167 -26
  27. package/packages/tui/lib/main.mjs +53 -9
  28. package/packages/tui/lib/model.mjs +2 -0
  29. package/packages/tui/lib/store.mjs +18 -3
  30. package/packages/tui/lib/term/keys.mjs +135 -33
  31. package/packages/tui/lib/term/kitty.mjs +198 -0
  32. package/packages/tui/lib/term/through.mjs +128 -14
  33. package/packages/tui/lib/term/tty.mjs +43 -12
  34. package/packages/tui/lib/views/frame.mjs +1 -1
  35. package/packages/tui/lib/views/help.mjs +52 -13
  36. package/skills/oats-getting-started/SKILL.md +96 -28
package/docs/tui.md CHANGED
@@ -357,7 +357,9 @@ fit; the detail shows them whole. The TUI's own words end the same way:
357
357
  key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
358
358
  among them, but for **[the leader](#the-leader)** (`Alt+O`, `Ctrl+\` on
359
359
  macOS, unless [`tui.json`](#change-the-keys-tuijson) names another), the
360
- one key the TUI takes from the agent. The leader then `Esc` gives the
360
+ one key the TUI takes from the agent, and the [chords](#chords) while your
361
+ terminal sends them. Under the kitty keyboard protocol every key reaches
362
+ the agent as the bytes it sends without it. The leader then `Esc` gives the
361
363
  focus to the list; the leader twice types the leader into the agent; the
362
364
  leader then another key does what that key does from anywhere. While the
363
365
  terminal has the focus the cheat sheet names those three:
@@ -1060,6 +1062,7 @@ The line after leaving says so and names `oats status` to see it.
1060
1062
  | `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
1061
1063
  | `Alt+O` (`Ctrl+\` on macOS) | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
1062
1064
  | `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
1065
+ | `Ctrl+Shift+K`, `Ctrl+Tab` and the other [chords](#chords) | where your terminal sends them, what the leader then a key does, from every focus |
1063
1066
  | `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
1064
1067
  | `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
1065
1068
  | `N` | spawns another of the selected instance's soul: its preview |
@@ -1081,12 +1084,12 @@ instance can always be read, however many they are. The selection stays
1081
1084
  where it is, and the list returns to it at the next key that moves it.
1082
1085
 
1083
1086
  The help screen is generated from the table the program acts on, so it
1084
- always lists the keys that work, the leader's among them, the palette's
1085
- and the spawn prompt's, with the marks and with what this version does not
1086
- do. Its top row has the time of the read and the count of withheld rows
1087
+ always lists the keys that work, the leader's among them, the chords while
1088
+ your terminal sends them, the palette's and the spawn prompt's, with the
1089
+ marks and with what this version does not do. Its top row has the time of the read and the count of withheld rows
1087
1090
  ([What it shows](#what-it-shows)). The movement keys scroll it. While
1088
1091
  a terminal has the focus the table's keys are the agent's: the leader alone
1089
- is the TUI's.
1092
+ is the TUI's, with the chords while your terminal sends them.
1090
1093
 
1091
1094
  ### The leader
1092
1095
 
@@ -1140,7 +1143,9 @@ to use Option as Meta.
1140
1143
  two keys reaches the agent unchanged: in vim that is "leave insert mode,
1141
1144
  open a line". Over a slow link two keys typed apart can arrive in one
1142
1145
  read and act as the leader, and one `Alt+O` can arrive split and reach
1143
- the agent as `Esc` and `o`.
1146
+ the agent as `Esc` and `o`. Under the kitty keyboard protocol
1147
+ ([Chords](#chords)) there is no timing: `Alt+O` is one sequence and `Esc`
1148
+ another, so each is told exactly, in a terminal and in the list.
1144
1149
  - **In the list no leader is needed:** the plain keys work as they always
1145
1150
  have, and the leader works there too.
1146
1151
  - **What was open under it is settled first,** from whatever view: a
@@ -1152,6 +1157,70 @@ to use Option as Meta.
1152
1157
  - **The table is fixed** in this version: `keys` in `tui.json` rebinds the
1153
1158
  plain keys, and `open.detachKey` the leader.
1154
1159
 
1160
+ ### Chords
1161
+
1162
+ Where your terminal lets them through, the OATS Desktop's Ctrl+Shift chords
1163
+ work in `oats tui` too, as extras: each does what the leader then a key
1164
+ does, from every focus, a terminal's too, and never reaches the agent. The
1165
+ leader stays the key that always works, and the cheat sheet does not name
1166
+ the chords.
1167
+
1168
+ | Chord (Linux and Windows) | Does: the leader then |
1169
+ |---|---|
1170
+ | `Ctrl+Shift+K` | `k`, the palette |
1171
+ | `Ctrl+Shift+P` | `n`, spawn an agent |
1172
+ | `Ctrl+Tab`, `Ctrl+Shift+Tab` | `Right`, `Left`: the next or the previous tab |
1173
+ | `Ctrl+Shift+W` | `w`, close the shown terminal |
1174
+ | `Ctrl+Shift+F` | `/`, the filter |
1175
+ | `Ctrl+Shift+E`, `Ctrl+Shift+O` | `\|`, `-`: split right, split down |
1176
+
1177
+ On macOS the Desktop's chords hold ⌘, which a terminal never passes to a
1178
+ program: there `Ctrl+Tab` and `Ctrl+Shift+Tab` are the only chords. The
1179
+ chords are the Desktop's (`CHORDS` in `packages/client/keymap.mjs`), and the
1180
+ TUI keeps no copy. The Desktop's Ctrl+1, Ctrl+2 and Ctrl+3 (its stages) are
1181
+ its own.
1182
+
1183
+ - **Only where the terminal says it can.** A terminal sends these keys apart
1184
+ from `Ctrl+K`, `Ctrl+P` and the others only under the kitty keyboard
1185
+ protocol. As it takes the terminal, `oats tui` asks for the protocol with
1186
+ flags 1 and 4 (`CSI > 5 u`) and asks the terminal which flags it has
1187
+ (`CSI ? u`). Only when the answer holds flag 1 does it read the protocol,
1188
+ take the chords and list them in the help. With no answer within 2
1189
+ seconds, or one without flag 1, it pops the protocol, and the rest of the
1190
+ run is as without it. The answer may come split and late over a slow
1191
+ link, so until it comes (at most those 2 seconds) an `Esc` pressed on its
1192
+ own may wait for the next key or for the wait's end, as it may begin the
1193
+ answer. foot, Ghostty, kitty, Alacritty and WezTerm answer.
1194
+ GNOME Terminal and the other VTE terminals, and Terminal.app, do not:
1195
+ there the chords are absent.
1196
+ - **Your terminal may take some first.** foot takes Ctrl+Shift+C, V, R, N,
1197
+ O, U, Z, X and Q for itself, so `Ctrl+Shift+O` never reaches `oats tui`
1198
+ there. The help says so.
1199
+ - **Every other key reads as it does without the protocol.** `Ctrl+Shift+L`
1200
+ is `Ctrl+L`, `Ctrl+Enter` is `Enter`, and so on: the protocol only adds
1201
+ the chords, and tells `Alt+O` from `Esc` then `o` exactly
1202
+ ([The leader](#the-leader)).
1203
+ - **An agent gets what it gets without the protocol.** Every key typed
1204
+ into an agent's terminal is turned back into the bytes the same key sends
1205
+ without it, the legacy encoding of xterm and the terminals that follow it:
1206
+ text, Shift, Ctrl, Alt, Esc, Tab, Enter, Backspace, the arrows, the
1207
+ function keys and the keypad, with their modifiers. The TUI types those
1208
+ bytes into the agent's viewer (`tmux attach` on the agents' server). It
1209
+ changes no tmux setting, `extended-keys` included, so the agent's program
1210
+ gets the same bytes as before. A key that sends nothing without the
1211
+ protocol (F13 and above, the media keys) is not typed.
1212
+ - **One limit: Shift with Alt or Ctrl on a key that is not a letter.** With
1213
+ flag 4 the terminal says which character Shift makes on your layout, and
1214
+ the TUI types exactly that. A terminal that confirms flag 1 alone does not
1215
+ say, and then the TUI uses the US layout's character for the 21 keys that
1216
+ are not letters (`Shift+Alt+2` is `Alt+@`), which your layout may not
1217
+ make.
1218
+ - **It is always popped** (`CSI < u`): on every way out
1219
+ ([below](#what-it-changes-in-your-terminal-and-restores)), at a suspend
1220
+ (and pushed again on return), and before any other program is given the
1221
+ terminal: the shell at a suspend is the only one `oats tui` ever gives
1222
+ it to.
1223
+
1155
1224
  ### The palette
1156
1225
 
1157
1226
  The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
@@ -1218,9 +1287,12 @@ and scrolling keep working.
1218
1287
 
1219
1288
  ## Change the keys: `tui.json`
1220
1289
 
1221
- `oats tui` reads `$XDG_CONFIG_HOME/oats/tui.json` when `XDG_CONFIG_HOME` is
1222
- an absolute path, else `~/.config/oats/tui.json`, once, at the start. It
1223
- never writes it. With no file the keys are the ones above.
1290
+ `oats tui` reads `~/.oats/config/tui.json` once, at the start: beside the
1291
+ kernel's own files, so it is `$OATS_HOME_DIR/config/tui.json` when
1292
+ `OATS_HOME_DIR` is set (the same rule as this computer's list of
1293
+ deployments). `XDG_CONFIG_HOME` is not read for it. It never writes the file,
1294
+ except to [move it](#the-move-from-configoats) from where earlier versions
1295
+ read it. With no file the keys are the ones above.
1224
1296
 
1225
1297
  ```json
1226
1298
  { "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false, "open": { "detachKey": "F12" } }
@@ -1293,6 +1365,47 @@ A name from the file is repeated in a line only when it is plain printable
1293
1365
  ASCII of at most 40 characters. More than twenty problems are counted, not
1294
1366
  listed.
1295
1367
 
1368
+ ### The move from `.config/oats`
1369
+
1370
+ Earlier versions read `$XDG_CONFIG_HOME/oats/tui.json` when
1371
+ `XDG_CONFIG_HOME` is set, not empty and an absolute path, else
1372
+ `~/.config/oats/tui.json`: the old file. Before it reads the new one, every
1373
+ start looks at both:
1374
+
1375
+ | Old file | New file | `oats tui` |
1376
+ |---|---|---|
1377
+ | there | not there | copies the old file's bytes to the new path, then renames the old file `tui.json.migrated` beside it, then reads the new one |
1378
+ | there | there | refuses: `<old> is no longer read: the TUI reads <new>. Copy what you need into <new>, then remove <old>` |
1379
+ | not there | there | reads the new one |
1380
+ | not there | not there | uses the defaults |
1381
+
1382
+ - "There" means an entry is at that path: a symbolic link counts, a link to
1383
+ nothing included, so a link to nothing as the old file is reported rather
1384
+ than guessed at.
1385
+ - The copy is the file's bytes, not its settings: a file the TUI cannot use
1386
+ is moved as it is, then refused against the new path like any other. The
1387
+ new file is made with mode `0600`, and the directories it needs with
1388
+ `0700`. It is written to a file of its own beside its path, then put in
1389
+ place, by a hard link, so it is never half written and never written
1390
+ over another file.
1391
+ - A link as the old file is renamed itself, not followed: what it points at
1392
+ is copied, and its target is left as it was.
1393
+ - When the move cannot be made, nothing is left half done and the start
1394
+ stops: `cannot move <old> to <new> (<reason>); move it yourself`. The
1395
+ reason is a link to nothing, not a regular file, larger than 64 KiB,
1396
+ `tui.json.migrated is there already` (a backup is never written over),
1397
+ `this file system has no hard links` (FAT, exFAT, some network mounts:
1398
+ there the file cannot be put in place whole without a risk of writing over
1399
+ another, so it is not moved), or the code of the error, as `EACCES`. When the rename fails after the copy is
1400
+ made, the copy is deleted first.
1401
+ - To move it yourself, put the file at the new path and remove the old one
1402
+ (or rename it to anything but `tui.json`).
1403
+ - Two runs that start at once move it once. The one that finds a new file
1404
+ placed by the other since it looked asks again: once its old file is gone
1405
+ it reads the new one; while an old file is still there (the other's, not
1406
+ yet renamed, or its own, with another `XDG_CONFIG_HOME`) it refuses as for
1407
+ both files, and never reads settings it was not moving: start it again.
1408
+
1296
1409
  ## What it reads, and what it runs
1297
1410
 
1298
1411
  `oats tui` decodes no kernel answer itself: it runs the readers it shares
@@ -1508,7 +1621,7 @@ with the Desktop (`packages/client/`).
1508
1621
  | spawn an agent on another machine | `oats spawn <soul> --server <id>` |
1509
1622
  | spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
1510
1623
  | see a capability's skills and files | `oats capabilities show <name>` |
1511
- | add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
1624
+ | add a machine to this workspace | `oats server connect <id> --ssh <alias> --dir <path on that machine>` |
1512
1625
  | check a machine | `oats server check <id>` |
1513
1626
  | remove a machine | `oats server remove <id>` |
1514
1627
  | open a deployment that is not listed | `oats tui --dir <path>` |
@@ -1550,10 +1663,15 @@ This is the complete list. On start, in this order:
1550
1663
  2. the alternate screen (`CSI ?1049h`), so your scrollback is untouched;
1551
1664
  3. the cursor hidden (`CSI ?25l`);
1552
1665
  4. autowrap off (`CSI ?7l`);
1553
- 5. bracketed paste on (`CSI ?2004h`).
1666
+ 5. bracketed paste on (`CSI ?2004h`);
1667
+ 6. the kitty keyboard protocol pushed, with flags 1 and 4 (`CSI > 5 u`), and
1668
+ the terminal asked which flags it has (`CSI ? u`); a terminal that does
1669
+ not know the protocol ignores both. With no answer in 2 seconds it is
1670
+ popped ([Chords](#chords)).
1554
1671
 
1555
- On the way out, the reverse: bracketed paste off, autowrap on, the style
1556
- reset (`CSI 0m`), the cursor shown, the alternate screen left, raw mode off.
1672
+ On the way out, the reverse: the protocol popped (`CSI < u`), bracketed
1673
+ paste off, autowrap on, the style reset (`CSI 0m`), the cursor shown, the
1674
+ alternate screen left, raw mode off.
1557
1675
 
1558
1676
  While it draws:
1559
1677
 
@@ -1620,10 +1738,11 @@ alone. The next run removes the directory that is left, with its `tmux`,
1620
1738
  ## What it never does
1621
1739
 
1622
1740
  - It switches on **no mouse reporting, no focus reporting, no keyboard
1623
- protocol and no keypad or cursor-key mode**, and leaves no synchronized
1624
- update on between frames.
1741
+ protocol but the kitty one with flags 1 and 4 ([Chords](#chords)), and no
1742
+ keypad or cursor-key mode**, and leaves no synchronized update on between
1743
+ frames.
1625
1744
  - It writes **no window title, no clipboard sequence, no bell**, and no query
1626
- that expects the terminal to reply.
1745
+ that expects the terminal to reply but the kitty keyboard protocol's.
1627
1746
  - **Its own words and marks use only your terminal's own sixteen colours**
1628
1747
  and bold, dim, underline and reverse: no 256-colour or RGB value and no
1629
1748
  background fill, so your theme stays the theme. An open terminal shows
@@ -1682,6 +1801,8 @@ alone. The next run removes the directory that is left, with its `tmux`,
1682
1801
  | `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 |
1683
1802
  | `E_BAD_ARGS` | any argument other than `--dir <path>`, `--ascii` and `--help`, or `--dir` with no path. One line on stderr with the usage, exit 1 | `oats tui --help` |
1684
1803
  | `E_TUI_CONFIG` | `tui.json` cannot be honoured. One line per problem on stderr, exit 1 | fix the file as the line says, or remove it |
1804
+ | `E_TUI_CONFIG` | the [old `tui.json`](#the-move-from-configoats) and the new one are both there: `` `oats tui`: <old> is no longer read: the TUI reads <new>. Copy what you need into <new>, then remove <old> ``. One line on stderr, exit 1 | as the line says |
1805
+ | `E_TUI_CONFIG` | the [old `tui.json`](#the-move-from-configoats) could not be moved: `` `oats tui` cannot move <old> to <new> (<reason>); move it yourself ``. One line on stderr, exit 1 | move it yourself: the file at the new path, the old one removed |
1685
1806
  | `E_NO_DEPLOYMENT` | with `--dir`, no directory at or above it holds an `oats-local.yaml`: `no OATS deployment at or above <dir>`. One line on stderr, exit 1 | `oats tui --dir <path>` with a deployment, or `cd` into one |
1686
1807
  | `E_NO_DEPLOYMENT` | without `--dir`, no directory at or above the start holds an `oats-local.yaml`, and this computer's list of deployments holds none: `no deployment at or above <dir>, and this computer's list of deployments holds none (E_NO_DEPLOYMENT): \`oats tui --dir <path>\` opens one (and lists it), \`oats onboard <dir> --workspace <ref>\` creates one`. One line on stderr, exit 1 | as the line says |
1687
1808
  | the kernel's code (`E_DEPLOYMENTS_BUSY`, `E_DEPLOYMENTS_INVALID`, `E_DEPLOYMENTS_VERSION`, …) | without `--dir` and outside every deployment, this computer's list of deployments could not be read: `` `oats tui` could not read this computer's list of deployments (<code>): <the kernel's message> ``. One line on stderr, exit 1 | what the kernel's message says |
package/docs/upgrading.md CHANGED
@@ -93,7 +93,7 @@ Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
93
93
  release. Read 0.62.0's Upgrade section and keep this order: install the
94
94
  Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
95
95
  `>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`, the 0.64.0
96
- Desktop `>=0.26.0 <0.65.0`, the 0.65.0 Desktop `>=0.26.0 <0.66.0`), then that
96
+ Desktop `>=0.26.0 <0.65.0`, the 0.65.0 Desktop `>=0.26.0 <0.66.0`, the 0.66.0 Desktop `>=0.26.0 <0.67.0`), then that
97
97
  release's CLI and matching pi bridge. Only **after
98
98
  installing that CLI**, run its setup conversion once per user on each host,
99
99
  from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
@@ -54,7 +54,7 @@ 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.13.3 # bare version → resolves through the official catalog
57
+ oats.framework: v1.13.4 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.2.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
@@ -697,7 +697,9 @@ only. Which deployments a client has open stays with that client.
697
697
  nothing.
698
698
  - `oats deployments add [<dir>]`, which the clients run when they open a
699
699
  deployment, and people by hand. It lists the deployment at or above `<dir>`
700
- (default: the current directory), found as every kernel `--dir` finds it.
700
+ (default: the current directory): the nearest directory whose
701
+ `oats-local.yaml` is a regular file, not a link. A directory or a link of
702
+ that name is not a deployment's file and is passed over.
701
703
  - **Every kernel command that resolves a deployment that is not listed yet**
702
704
  lists it (`via: cli`): `status`, `spawn`, `sync`, `session`, `doctor`,
703
705
  `retire` and the others that read a local deployment, from inside an
@@ -717,6 +719,11 @@ only. Which deployments a client has open stays with that client.
717
719
  answer and exit status are the same whether or not it listed anything.
718
720
  - A command routed with `--server` never lists anything: the host's path is
719
721
  not this computer's.
722
+ - A deployment under a temporary directory (`os.tmpdir()`, `/tmp`,
723
+ `/private/tmp` or `/var/folders`, each compared after realpath) is never
724
+ listed this way, since test fixtures live there and would stay in the list
725
+ as `missing`; `oats deployments add`, `oats onboard` and a client opening it
726
+ still list one.
720
727
  - A deployment inside a linked Git worktree or submodule is listed by the
721
728
  first command that resolves its instance root (`status`, `spawn`,
722
729
  `session` and the like), not by `sync`, `doctor` and the other
@@ -23,8 +23,8 @@
23
23
  */
24
24
 
25
25
  import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, statSync } from "node:fs";
26
- import { homedir } from "node:os";
27
- import { basename, dirname, isAbsolute, join, resolve } from "node:path";
26
+ import { homedir, tmpdir } from "node:os";
27
+ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
28
28
  import { canonicalDeploymentPath } from "./core.mjs";
29
29
  import { withDirLock } from "./dir-lock.mjs";
30
30
  import { writeFileAtomic } from "./packages.mjs";
@@ -242,11 +242,12 @@ export function listDeployments() {
242
242
  return { deploymentsApi: DEPLOYMENTS_API, file: deploymentsFile(), deployments, imports: doc.imports };
243
243
  }
244
244
 
245
- /** The deployment at or above `dir`: the first directory walking up that holds an oats-local.yaml
246
- * (as every kernel `--dir` finds it), or null. */
245
+ /** The deployment at or above `dir`: the first directory walking up whose oats-local.yaml is a
246
+ * regular file, not a link (the rule a client admits a deployment by, and the list's `ok`), or
247
+ * null. Anything else of that name (a directory, a link) is passed over (awebai/oats#1397). */
247
248
  export function deploymentAtOrAbove(dir) {
248
249
  for (let d = resolve(dir); ; d = dirname(d)) {
249
- try { lstatSync(join(d, "oats-local.yaml")); return d; } catch { /* not here */ }
250
+ try { if (lstatSync(join(d, "oats-local.yaml")).isFile()) return d; } catch { /* not here */ }
250
251
  if (dirname(d) === d) return null;
251
252
  }
252
253
  }
@@ -297,6 +298,17 @@ function inGitFileWorkTree(dir) {
297
298
  }
298
299
  }
299
300
 
301
+ /** The temporary directories, as the auto-add knows them (awebai/oats#1397): os.tmpdir(), /tmp,
302
+ * /private/tmp and /var/folders (macOS's per-user ones), each by its realpath. */
303
+ export const TEMPORARY_DIRECTORIES = Object.freeze(["/tmp", "/private/tmp", "/var/folders"]);
304
+ /** Whether the real path `real` is one of the temporary directories or under one. */
305
+ export function underTemporaryDirectory(real) {
306
+ return [tmpdir(), ...TEMPORARY_DIRECTORIES].some((dir) => {
307
+ const top = canonicalHomePath(dir);
308
+ return dirname(top) !== top && (real === top || real.startsWith(top + sep)); // a TMPDIR of / is not taken
309
+ });
310
+ }
311
+
300
312
  /** The auto-add of awebai/oats#1390 (amendment and its performance budget): `root`, the deployment
301
313
  * directory the command itself resolved (`canonical`: the root ensureRoot canonicalized), is
302
314
  * listed when it is not. A listed deployment (live or tombstoned) costs one lock-free bounded read
@@ -305,6 +317,9 @@ function inGitFileWorkTree(dir) {
305
317
  * to the commands that resolve its canonical root, from lstat alone: its stored path is the
306
318
  * primary checkout's, which only Git can tell;
307
319
  * - another spelling of a listed deployment (a link, /var for /private/var) costs a realpath;
320
+ * - an unlisted root whose realpath is under a temporary directory is never listed by it
321
+ * (awebai/oats#1397): test fixtures live there, and would stay in the list as `missing`. An
322
+ * explicit add, onboard and the imports still list such a root;
308
323
  * - only an unlisted deployment is canonicalized (a Git probe) and tries the lock once (no wait:
309
324
  * busy skips, the next command tries again) to add it `via: cli`.
310
325
  * Best effort and silent: it never throws or prints. → `"listed" | "added" | "skipped"`. */
@@ -318,6 +333,7 @@ export function listResolved(root, { canonical = false } = {}) {
318
333
  const real = canonicalHomePath(root);
319
334
  if (known(real)) return "listed";
320
335
  if (!canonical && real !== root && inGitFileWorkTree(real)) return "skipped";
336
+ if (underTemporaryDirectory(real)) return "skipped";
321
337
  const path = canonicalListPath(root);
322
338
  if (known(path)) return "listed";
323
339
  return updateDeployments((d, now) => (addRow(d, path, "cli", now, { revive: false }) ? "added" : "listed"), { wait: 0 });
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.29.0",
11
+ "ref": "v1.30.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.13.3",
46
+ "ref": "oats-framework/v1.13.4",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.65.0",
3
+ "version": "0.66.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.66.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.67.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
52
52
  // carry a `description` for every kind and `<kind> update <id> --description`
53
53
  // sets one (feature `automation-descriptions`, which gates the Desktop's
54
54
  // summary writes). The Desktop v1 surface is otherwise unchanged.
55
- export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 66, 0] };
55
+ export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 67, 0] };
56
56
  /** The band as humans read it — derived, never hand-spelled, so the probe
57
57
  * rejection reason, the backend's /api status and the degradation card can
58
58
  * never disagree with the numbers actually enforced above. */
@@ -1,18 +1,22 @@
1
- /** The keys both clients share: the leader, the table read after it, and the plain keys of the list
2
- * of instances. Written down once, here; the Desktop reads its defaults from it, and the TUI's own
3
- * table (packages/tui/lib/actions.mjs LEADER) is held equal to LEADER_TABLE by the root test
4
- * test/keymap-parity.test.mjs until the TUI imports this module.
1
+ /** The keys both clients share: the leader, the table read after it, the plain keys of the list
2
+ * of instances, and the chords. Written down once, here; the Desktop and the TUI read their defaults
3
+ * from it (packages/tui/lib/actions.mjs LEADER is LEADER_TABLE, and the TUI's test
4
+ * packages/tui/test/keymap.test.mjs fails on a `does` the TUI does not handle).
5
5
  *
6
6
  * Pure data and readers: no state, no DOM, no imports. Every value is frozen.
7
7
  *
8
8
  * Key ids are the TUI's spelling (packages/tui/lib/term/keys.mjs keyId): one character as itself,
9
9
  * case kept (`n`, `N`, `|`, `?`, `/`, `-`); named keys `up` `down` `left` `right` `tab` `escape`
10
- * `space` `enter` `home` `end` `pageup` `pagedown`; modifiers as `ctrl+` / `alt+` prefixes.
10
+ * `space` `enter` `home` `end` `pageup` `pagedown`; modifiers as `ctrl+` / `alt+` / `shift+`
11
+ * prefixes, in that order. A chord adds two: `shift+` with Ctrl and a letter (`ctrl+shift+k`, which
12
+ * the TUI reads only under the kitty keyboard protocol), and `cmd+`, first, for macOS's Command
13
+ * (`cmd+k`, the Desktop's ⌘K), which a terminal never passes to a program.
11
14
  *
12
- * leaderKey(isMac) -> the leader's key id on that platform "ctrl+\\" / "alt+o"
13
- * leaderDoes(key) -> what the leader then does for a key id, or null
14
- * plainKeys(does) -> the plain key ids of an action (empty when it has none)
15
- * leaderRows() -> LEADER_TABLE
15
+ * leaderKey(isMac) -> the leader's key id on that platform "ctrl+\\" / "alt+o"
16
+ * leaderDoes(key) -> what the leader then does for a key id, or null
17
+ * plainKeys(does) -> the plain key ids of an action (empty when it has none)
18
+ * leaderRows() -> LEADER_TABLE
19
+ * chordKey(does, isMac) -> the chord's key id on that platform, or null
16
20
  *
17
21
  * `does` names an action, not a client's code: each client maps it to its own. */
18
22
 
@@ -82,6 +86,23 @@ export const PLAIN_KEYS = Object.freeze([
82
86
  { does: "help", keys: ["?"] },
83
87
  ].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
84
88
 
89
+ /** The chords: one key that does what the leader then a key does, the Desktop's direct chords whose
90
+ * action the TUI has too, per platform (`mac`, `other`). The Desktop's DEFAULT_KEYMAP reads these
91
+ * entries from here (docs/desktop-keyboard.md). The TUI takes the `other` ones, and the `mac` ones
92
+ * without `cmd+`, while the terminal confirms the kitty keyboard protocol (docs/tui.md, "Chords"),
93
+ * as extras: the leader stays the key that always works. The Desktop's Ctrl+1/2/3 (the stages) are
94
+ * the Desktop's own and are not here. */
95
+ export const CHORDS = Object.freeze([
96
+ { does: "palette", mac: "cmd+k", other: "ctrl+shift+k" },
97
+ { does: "spawn", mac: "cmd+p", other: "ctrl+shift+p" },
98
+ { does: "tab-next", mac: "ctrl+tab", other: "ctrl+tab" },
99
+ { does: "tab-previous", mac: "ctrl+shift+tab", other: "ctrl+shift+tab" },
100
+ { does: "close-terminal", mac: "cmd+w", other: "ctrl+shift+w" },
101
+ { does: "filter", mac: "cmd+f", other: "ctrl+shift+f" },
102
+ { does: "split-right", mac: "cmd+\\", other: "ctrl+shift+e" },
103
+ { does: "split-down", mac: "cmd+shift+\\", other: "ctrl+shift+o" },
104
+ ].map((entry) => Object.freeze({ ...entry })));
105
+
85
106
  const NONE = Object.freeze([]);
86
107
 
87
108
  /** The leader's key id on macOS (`true`) or elsewhere. */
@@ -104,3 +125,9 @@ export function plainKeys(does) {
104
125
  export function leaderRows() {
105
126
  return LEADER_TABLE;
106
127
  }
128
+
129
+ /** The key id of the chord that does `does` on macOS (`true`) or elsewhere, or null when none does. */
130
+ export function chordKey(does, isMac) {
131
+ const entry = CHORDS.find((each) => each.does === does);
132
+ return entry === undefined ? null : isMac ? entry.mac : entry.other;
133
+ }
@@ -1,4 +1,4 @@
1
- /* oats desktop — a workspace's own machines (#517): the gates, the Add a machine defaults and field
1
+ /* oats desktop — a workspace's own machines (#517): the gates, the Add a machine Name default and field
2
2
  rules, and the step rows of `oats server connect --json` and `oats aweb connect --json` as the CLI
3
3
  sends them (docs/desktop-cli-api.md; interface §2 and §4).
4
4
 
@@ -37,10 +37,6 @@ export function machineName(host, deploymentDir) {
37
37
  return `${host}-${basename(deploymentDir)}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-{2,}/g, '-')
38
38
  .replace(/^-+/, '').slice(0, 64).replace(/-+$/, '');
39
39
  }
40
- /** The default Folder on that machine: `~/Agents/<this deployment dir basename>`. */
41
- export function machineFolder(deploymentDir) {
42
- return `~/Agents/${basename(deploymentDir)}`;
43
- }
44
40
 
45
41
  /** The first field that the kernel would refuse, as `{ field, text }`, or null. */
46
42
  export function machineFieldProblem({ id, host, folder }) {
@@ -31,7 +31,8 @@ import { captureDefaultRootPlan } from "../lib/capture-default-roots.mjs";
31
31
  import { captureCommandPass } from "../lib/capture-command-output.mjs";
32
32
  import { captureCommandEntry } from "../lib/capture-command.mjs";
33
33
  import { IgnoreError, loadIgnore } from "../lib/ignore.mjs";
34
- import { preflightCaptureService, applyCaptureService, captureSetupSnapshot, recheckCaptureSetup, writeCaptureSetup } from "../lib/capture-service-install.mjs";
34
+ import { preflightCaptureService, applyCaptureService } from "../lib/capture-service-install.mjs";
35
+ import { captureSetupSnapshot, recheckCaptureSetup, writeCaptureSetup } from "../lib/capture-setup-write.mjs";
35
36
  import { captureRemedyCommand } from "../lib/capture-health.mjs";
36
37
 
37
38
  // The node written into what outlives this process: the hooks and the
@@ -243,7 +244,14 @@ try {
243
244
  for (const { snapshot, contents } of hooks) {
244
245
  if (!contents) console.log(`hooks: ${snapshot.path} already installed`);
245
246
  else if (dry) console.log(`hooks: would install Stop+SessionEnd capture in ${snapshot.path}`);
246
- else { writeCaptureSetup(snapshot, contents, createdParents); summary.hooks.push(snapshot.path); console.log(`hooks: installed Stop+SessionEnd capture in ${snapshot.path}`); }
247
+ else {
248
+ try { writeCaptureSetup(snapshot, contents, createdParents); }
249
+ catch (error) {
250
+ if (error.published) summary.hooks.push(`${snapshot.path} (publication may have occurred at ${oneLine(error.stage)}; durability was not established)`);
251
+ throw error;
252
+ }
253
+ summary.hooks.push(snapshot.path); console.log(`hooks: installed Stop+SessionEnd capture in ${snapshot.path}`);
254
+ }
247
255
  }
248
256
  if (dry) console.log("dry run: no first capture pass");
249
257
  else {
@@ -1533,8 +1533,11 @@ the first pass still uses the running Node. These are user-manager definitions,
1533
1533
  not deployment automation timers. No external wrapper is removed.
1534
1534
 
1535
1535
  The setup coordinator prepares hook edits in memory, then
1536
- `capture-service-install.mjs` snapshots every named service target and inspects
1537
- applicable manager state before any service/file/hook/capture mutation.
1536
+ `capture-service-install.mjs` uses `capture-setup-write.mjs` to snapshot every
1537
+ named service target and inspects applicable manager state before any
1538
+ service/file/hook/capture mutation. The shared module owns checked setup
1539
+ publication independently of manager policy; the service module retains its
1540
+ snapshot/recheck/write exports for existing callers.
1538
1541
  Snapshots retain regular-file bytes and identity or the symlink's own identity
1539
1542
  and target, plus ancestor identities and explicit missing-ancestor records. Reads are limited to 1 MiB per target;
1540
1543
  unknown reads, nonregular targets and unsupported manager output refuse.
@@ -1574,6 +1577,11 @@ Apply rechecks file/ancestor identities and manager ownership/enablement.
1574
1577
  Replaced bytes or symlinks are saved nonoverwriting in a reported datable
1575
1578
  `<root>/service-backups/<date>-<unique-id>/` directory. Symlink backups
1576
1579
  preserve the link instead of reading or removing an external wrapper target.
1580
+ Backup bytes and directory/symlink entries are not fsynced and cannot be relied
1581
+ on as power-loss-safe recovery. Durability of a replacement does not establish
1582
+ backup durability; this is tracked separately in
1583
+ [backup durability follow-up #1410](https://github.com/awebai/oats/issues/1410).
1584
+
1577
1585
  An ancestor absent at preflight must remain absent until this apply creates it.
1578
1586
  Creation proceeds one directory at a time without recursive adoption of an
1579
1587
  existing path; each created non-link directory's identity is retained in a
@@ -1581,9 +1589,35 @@ per-apply map shared by subsequent service and hook writes. Newly introduced
1581
1589
  directories or links are not accepted as extra ancestry. Existing ancestor
1582
1590
  identities and observed symlink targets remain binding. The extra metadata
1583
1591
  checks and directory creation do not establish an atomic filesystem operation.
1584
- Each write uses a temporary file and another identity check before rename;
1585
- cleanup also refuses changed ancestry instead of unlinking through a redirected
1586
- path. An interrupted/refused write can leave its original temporary file.
1592
+ Each setup hook, service definition and pending-marker write uses the same
1593
+ checked publisher. It creates an exclusive 0600 temporary file, checks its
1594
+ open descriptor against the pathname, writes the complete contents and fsyncs
1595
+ the file before rename. After rechecking the saved target, temporary file and
1596
+ ancestors, it renames and fsyncs the containing directory through a checked
1597
+ directory descriptor. Newly created ancestor entries are synced in their
1598
+ containing directories, from the first missing parent toward the target,
1599
+ before creating the next child. A directory whose entry sync/open/close failed
1600
+ is not authorized for reuse by a subsequent write through the per-apply map.
1601
+ Required directory fsync failures, including an unsupported operation, refuse;
1602
+ there is no fallback that reports durability without the required sync.
1603
+
1604
+ A failure reports the target and stage, retains the primary cause and any
1605
+ scratch/descriptor cleanup failure, and exits nonzero. Before publication,
1606
+ the writer preserves the old target and removes only scratch whose saved
1607
+ identity and unchanged ancestry still prove ownership. Changed ancestry or a
1608
+ substituted temporary file revokes pathname cleanup; an interrupted/refused
1609
+ write can leave its original temporary file. After rename, a failed sync,
1610
+ close or identity recheck reports that publication may have occurred and
1611
+ durability was not established. It neither unlinks the new target nor claims
1612
+ rollback. A refused rename whose original target cannot be re-established is
1613
+ reported with the same uncertainty.
1614
+
1615
+ These are ordered filesystem durability operations, subject to the filesystem
1616
+ and storage device honoring fsync. Recording and injected I/O-fault fixtures
1617
+ check process-visible bytes, identities, permissions, failures and ordering;
1618
+ they do not reproduce or prove survival of a physical power loss. This setup
1619
+ publisher does not change ordinary capture transaction sync policy or the
1620
+ pending marker's activation/removal lifecycle.
1587
1621
  An expected manager unmask can remove only the saved named `/dev/null` link;
1588
1622
  other observed replacements refuse. These checks detect observed races, not
1589
1623
  an OS-wide atomic transaction over files and managers.
@@ -1654,7 +1688,12 @@ never as "nothing happened". After a service failure, `service changed` lines
1654
1688
  name, in order, what the failed apply had already changed: the replacement
1655
1689
  backup directory, each manager action completed (units stopped, disabled or
1656
1690
  unmasked, a job booted out), each definition written, and the pending-activation
1657
- marker written or a stale one removed. Setup has no `--json` mode.
1691
+ marker written or a stale one removed. A failed publication also retains any
1692
+ created-parent evidence and names a possibly published target and its failed
1693
+ stage in these lines. A hook published before a later durability failure is
1694
+ listed under `hooks written` with the same uncertainty and stage, rather than
1695
+ reported as `none`. These annotations describe possible changes, not successful
1696
+ durability or rollback. Setup has no `--json` mode.
1658
1697
 
1659
1698
  Fake-manager and isolated CLI fixtures exercise this ordering and refusal
1660
1699
  contract. Real-manager cases live in `test/capture-service-real-darwin.test.mjs`