@awebai/oats 0.69.11 → 0.69.14

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 (72) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +176 -184
  3. package/docs/capabilities.md +4 -1
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +246 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +376 -37
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +69 -6
  11. package/docs/implementation.md +86 -29
  12. package/docs/integrations.md +9 -5
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/knowledge.md +10 -3
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +42 -8
  17. package/docs/packages.md +101 -22
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.12.md +97 -0
  20. package/docs/release-notes/v0.69.13.md +767 -0
  21. package/docs/release-notes/v0.69.14.md +83 -0
  22. package/docs/schedules.md +26 -3
  23. package/docs/servers.md +181 -5
  24. package/docs/souls-and-instances.md +140 -11
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +30 -5
  27. package/docs/workspaces.md +32 -6
  28. package/lib/claim.mjs +21 -5
  29. package/lib/command-flags.mjs +238 -0
  30. package/lib/core.mjs +791 -563
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +126 -31
  33. package/lib/errors.mjs +1 -1
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/hot-reads.mjs +4 -3
  36. package/lib/instance-events.mjs +28 -6
  37. package/lib/instance-git.mjs +138 -13
  38. package/lib/instance-inspect.mjs +6 -1
  39. package/lib/instance-listing.mjs +80 -38
  40. package/lib/instance-resolution.mjs +56 -3
  41. package/lib/instance-upgrade.mjs +16 -20
  42. package/lib/launch-env-exec.sh +7 -0
  43. package/lib/launch-env.mjs +74 -0
  44. package/lib/launch-preference.mjs +19 -12
  45. package/lib/member-clone.mjs +7 -1
  46. package/lib/packages.mjs +74 -2
  47. package/lib/read-call.mjs +3 -0
  48. package/lib/reader.mjs +3 -2
  49. package/lib/refused-text.mjs +3 -2
  50. package/lib/remote.mjs +119 -27
  51. package/lib/retained-after-retire.mjs +2 -7
  52. package/lib/retire-git-forms.mjs +41 -0
  53. package/lib/retire-incomplete.mjs +96 -0
  54. package/lib/schedule.mjs +2 -1
  55. package/lib/servers.mjs +78 -23
  56. package/lib/session-resume.mjs +68 -53
  57. package/lib/session-seen.mjs +54 -5
  58. package/lib/start-env.mjs +13 -7
  59. package/lib/system-tools.mjs +1 -1
  60. package/lib/teams.mjs +11 -4
  61. package/lib/upgrade-state.mjs +13 -2
  62. package/lib/worktree.mjs +56 -7
  63. package/package-catalog.json +3 -3
  64. package/package.json +2 -1
  65. package/packages/client/instance-lifecycle.mjs +1 -1
  66. package/packages/client/lifecycle-contract.mjs +3 -1
  67. package/packages/client/session-resume-cli.mjs +2 -1
  68. package/packages/client/session-start.mjs +10 -7
  69. package/packages/client/workspace-cli.mjs +5 -1
  70. package/share/oats-login-receive +204 -0
  71. package/skills/oats-getting-started/SKILL.md +180 -49
  72. package/lib/tmux-config.mjs +0 -35
@@ -11,13 +11,13 @@ description: >-
11
11
  Use for "get started with OATS", "set up / install / adopt OATS", "set up
12
12
  OATS for this project", "join our OATS workspace", or when someone gives
13
13
  you this file or its URL. Download this file whole (`curl -fsSL
14
- https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md`)
14
+ https://raw.githubusercontent.com/oats-project/oats/main/skills/oats-getting-started/SKILL.md`)
15
15
  and follow it as written: a summary of it is not the procedure.
16
16
  ---
17
17
 
18
18
  **Read this whole file, never a summary of it.** If you only have a summary
19
19
  (a web fetch that summarises, say), download it whole with
20
- `curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md`
20
+ `curl -fsSL https://raw.githubusercontent.com/oats-project/oats/main/skills/oats-getting-started/SKILL.md`
21
21
  and follow it as written.
22
22
 
23
23
  # Getting started with OATS
@@ -33,7 +33,8 @@ A **workspace** is one Git repository declaring which repositories belong to
33
33
  an organisation and which packages it trusts. A **soul** is a durable agent
34
34
  role defined in Git; an **instance** is a soul at work, in its own home and
35
35
  terminal. A new workspace's setup expert is `oats.framework`'s soul
36
- `oats-setup-expert` (capabilities `oats.setup` and `oats.onboarding`),
36
+ `oats-setup-expert` (capabilities `oats.setup` and `oats.onboarding`, and
37
+ `oats.coordination-setup` from oats.framework 1.23.0),
37
38
  spawned as `<workspace>-oats-setup-expert`.
38
39
 
39
40
  **A machine found-list** is a JSON file in your prompt whose
@@ -46,6 +47,12 @@ tell the person this machine already has its workspace and steward, and
46
47
  stop. Wherever a later step says to ask the
47
48
  person, on a machine found-list you tell them what happened, as it is, and
48
49
  stop instead: the person answers nothing after step 1.
50
+ Step 1's machine round is always asked, even when the prompt that started
51
+ you says to ask for nothing more (an installer's "beyond starting this, ask
52
+ no other yes"). Its one yes, naming the changes, is the consent your
53
+ harness's permission check reads; without it, the check refuses each change
54
+ on its own (the repository, the aweb signup, the folder trust), and each
55
+ costs the person a round. After that yes, nothing more is asked.
49
56
 
50
57
  **How to work.**
51
58
  - **Ask first, then run.** Ask everything in one round (step 1), then run the
@@ -154,7 +161,15 @@ On a machine found-list, ask the machine's round below instead of this list.
154
161
 
155
162
  **First, step 2's checks.** They only read, so run them before the message
156
163
  (not its installs): the changes to their computer that the message lists
157
- are what they found missing.
164
+ are what they found missing. On Linux x64 they include the Desktop's system
165
+ libraries: a missing one goes on the list as a system package, dropped if
166
+ they decline the Desktop, so the Desktop's install needs no second yes.
167
+
168
+ **No GitHub account.** Their agents' shared setup and their projects live
169
+ on GitHub. When gh is not logged in, ask in the same message whether they
170
+ have a GitHub account. Without one, they make one, free, in their browser
171
+ at step 3, and nothing else changes: gh goes on the list of changes like
172
+ any missing tool, and you install it.
158
173
 
159
174
  **The message.** Ask three things, and in the same message propose
160
175
  everything else as defaults they accept with "ok" or change:
@@ -263,9 +278,9 @@ the final values in one short message before you go on. The rules:
263
278
  `PEP` and `GPT`.
264
279
 
265
280
  With a tracker, the agents keep using it: the line says so ("your agents
266
- use your GitHub issues; the setup assistant connects them") and step 7
267
- writes `tasks: none`; the setup expert connects the tracker with the
268
- person later. Without one, the line says "aweb's task list, shared by your
281
+ use your GitHub issues; the setup assistant offers to connect them") and
282
+ step 7 writes `tasks: none`; the setup expert offers to connect the
283
+ tracker with the person later. Without one, the line says "aweb's task list, shared by your
269
284
  agents". Ask only when unsure, as the final-values message's one open
270
285
  line, prefilled with the answer you'd pick: ticket keys the person didn't
271
286
  name, a project kept somewhere other than GitHub (its issues can't be
@@ -275,8 +290,9 @@ the final values in one short message before you go on. The rules:
275
290
  **The machine's round.** Read the found-list, then ask only these choices,
276
291
  together, each with its default and one line on what it is. Enter, or
277
292
  "yes", accepts every default. Nothing is asked after this round, and never
278
- a key. The use case, repositories and knowledge tools are not asked: the
279
- steward takes them up with the person later.
293
+ a key. Ask it even when your prompt says to ask nothing more (above). The
294
+ use case, repositories and knowledge tools are not asked: the steward takes
295
+ them up with the person later.
280
296
  - **The workspace:** a new one, the machine's own. Its name defaults to the
281
297
  hostname, lowercased, with every character outside `[a-z0-9-]` turned
282
298
  into `-` (`Ada's-Laptop` gives `ada-s-laptop`). Its repository defaults to
@@ -330,6 +346,13 @@ before the first line that needs `sudo`.
330
346
  uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g; { git config --global user.name && git config --global user.email; } >/dev/null || echo NO_GIT_IDENTITY
331
347
  ```
332
348
 
349
+ On Linux x64, also check the Desktop's system libraries, ALSA and FUSE 2
350
+ (what a missing one means is under "The Desktop's system libraries", below):
351
+
352
+ ```bash
353
+ for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
354
+ ```
355
+
333
356
  - **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
334
357
  caches; older Git works with whole-tree fetches); `gh` 2.49 or later
335
358
  (step 3 uses `gh attestation`).
@@ -360,15 +383,12 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g;
360
383
  ```bash
361
384
  sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
362
385
  ```
363
- - **The Desktop's system libraries** (x64): ALSA and FUSE 2. Check:
364
-
365
- ```bash
366
- for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
367
- ```
368
-
386
+ - **The Desktop's system libraries** (x64), from the check above, run
387
+ before step 1's message:
369
388
  - **ALSA missing:** the Desktop needs it, so step 1's list names its
370
- package: `libasound2t64` on Ubuntu 24.04 and Debian 13, `libasound2`
371
- before them, `alsa-lib` on Fedora.
389
+ package, to install with the other system packages: `libasound2t64`
390
+ on Ubuntu 24.04 and Debian 13, `libasound2` before them, `alsa-lib` on
391
+ Fedora.
372
392
  - **FUSE 2 missing:** install nothing. Step 10 starts the AppImage with
373
393
  `--appimage-extract-and-run`, which needs no FUSE.
374
394
  - **Passwords:** a line that needs `sudo` runs only after their yes in
@@ -380,18 +400,26 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g;
380
400
  whole-tree fetches, and go on.
381
401
  - **npm's global folder** must be writable for step 4's installs
382
402
  (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node under
383
- `/usr`, as NodeSource installs it), set a per-user prefix,
384
- `npm config set prefix ~/.local`, as step 1's list said (when Node will
385
- come from NodeSource, the list names the per-user folder and its PATH
386
- line). Then start each later command of yours with
387
- `export PATH="$HOME/.local/bin:$PATH"`, and add that line to their shell's
388
- startup file yourself, so their own terminal finds `oats` too, and tell
389
- them: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc` (for fish,
390
- `fish -c 'fish_add_path ~/.local/bin'` instead).
403
+ `/usr`, as NodeSource installs it), make the two changes step 1's list
404
+ named for it (when Node will come from NodeSource, the list names the
405
+ per-user folder and its PATH line), each as its own command, never
406
+ joined into one:
407
+ - **npm's per-user folder** (in `~/.npmrc`):
391
408
 
392
- ```bash
393
- RC="$HOME/.bashrc"; case "$SHELL" in *zsh) RC="$HOME/.zshrc";; esac; grep -qsF '$HOME/.local/bin' "$RC" || printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$RC"; echo "$RC"
394
- ```
409
+ ```bash
410
+ npm config set prefix ~/.local
411
+ ```
412
+ - **The line that puts it on their PATH** in their shell's startup file:
413
+ `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc` (for fish,
414
+ `fish -c 'fish_add_path ~/.local/bin'` instead), so their own terminal
415
+ finds `oats` too. Tell them which file.
416
+
417
+ ```bash
418
+ RC="$HOME/.bashrc"; case "$SHELL" in *zsh) RC="$HOME/.zshrc";; esac; grep -qsF '$HOME/.local/bin' "$RC" || printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$RC"; echo "$RC"
419
+ ```
420
+
421
+ Your own shell doesn't read their startup file, so start each later
422
+ command of yours with `export PATH="$HOME/.local/bin:$PATH"`.
395
423
  - **Windows** is not supported.
396
424
 
397
425
  ## 3. Log in to GitHub
@@ -411,7 +439,15 @@ fail with "could not read Username"), then go on below:
411
439
  gh auth setup-git
412
440
  ```
413
441
 
414
- If not, start the login yourself, detached and without a terminal (your
442
+ **When they have no GitHub account** (step 1), open GitHub's sign-up page
443
+ in their browser first: `open https://github.com/signup` on macOS,
444
+ `xdg-open https://github.com/signup` on Linux, or give them the URL if that
445
+ fails. Tell them it is free, and that they choose a username, an email and a
446
+ password there, in their browser, never in this conversation; GitHub emails
447
+ them a code to confirm the address. Wait until they say the account is
448
+ made, then start the login below.
449
+
450
+ If not logged in, start the login yourself, detached and without a terminal (your
415
451
  harness's background mode if it has one); gh prints a one-time code and a
416
452
  URL instead of opening a browser, and waits:
417
453
 
@@ -462,9 +498,21 @@ file: `oats-desktop-V-linux-x86_64.AppImage` on Linux x64,
462
498
  checksum and the release's attestation all pass:
463
499
 
464
500
  ```bash
465
- W="$(mktemp -d)" && echo "$W" && { nohup sh -c 'cd "$1" && gh release download "vV" -R awebai/oats -p "F" -p SHA256SUMS.txt && grep " F\$" SHA256SUMS.txt | sha256sum -c - && gh attestation verify "F" --repo awebai/oats && echo VERIFIED; echo DONE' sh "$W" </dev/null >"$W.log" 2>&1 & }
501
+ W="$(mktemp -d)" && echo "$W" && { nohup sh -c 'cd "$1" && gh release download "vV" -R oats-project/oats -p "F" -p SHA256SUMS.txt && L=$(grep " F\$" SHA256SUMS.txt) && printf "%s\n" "$L" | sha256sum -c - && { gh attestation verify "F" --repo oats-project/oats --signer-workflow oats-project/oats/.github/workflows/release.yml --source-ref refs/tags/vV || case vV in v0.[0-9].*|v0.[1-5][0-9].*|v0.6[0-8].*|v0.69.[0-9]|v0.69.1[0-2]) gh attestation verify "F" --owner awebai --signer-workflow awebai/oats/.github/workflows/release.yml --source-ref refs/tags/vV;; *) false;; esac; } && echo VERIFIED; echo DONE' sh "$W" </dev/null >"$W.log" 2>&1 & }
466
502
  ```
467
503
 
504
+ The attestation has two forms because the repository moved:
505
+ - **Releases after 0.69.12** are attested in `oats-project/oats`.
506
+ - **Releases up to 0.69.12** were signed in `awebai/oats`, and their
507
+ attestations stayed with the `awebai` organisation. The `case` tries this
508
+ second form only for those versions.
509
+
510
+ Each form accepts only its own repository's release workflow, run for the
511
+ tag `vV`. On an older release the log shows the first form's `HTTP 404`
512
+ before the second passes; that is not a failure. The checksum counts only
513
+ when `SHA256SUMS.txt` has a line for `F`, because on macOS `sha256sum` passes
514
+ empty or malformed input; the attestation checks the file itself.
515
+
468
516
  Write the folder it prints in as `<W>` in step 4.
469
517
 
470
518
  ## 4. Install OATS Desktop, the CLI and the messaging CLI
@@ -485,7 +533,7 @@ installed CLI's catalog:
485
533
  node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
486
534
  ```
487
535
 
488
- It prints the two refs, for example `oats-framework/v1.21.0 v1.35.0`. If the
536
+ It prints the two refs, for example `oats-framework/v1.23.0 v1.37.0`. If the
489
537
  framework's version (after the `/`) is below `1.19.0`, or with aweb
490
538
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
491
539
  skill: stop, and tell the person to wait for the next OATS
@@ -717,8 +765,8 @@ name: acme
717
765
  members:
718
766
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
719
767
  packages:
720
- oats.framework: v1.21.0 # the installed CLI's catalog versions (below)
721
- oats.aweb: v1.35.0 # messaging: agent identities, mail and chat
768
+ oats.framework: v1.23.0 # the installed CLI's catalog versions (below)
769
+ oats.aweb: v1.37.0 # messaging: agent identities, mail and chat
722
770
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
723
771
  defaults:
724
772
  capabilities:
@@ -759,9 +807,11 @@ workspace: git:github.com/acme/acme-oats
759
807
  which named it, without asking again; show the person the files only if
760
808
  they ask. When others can push to the repository (`gh api
761
809
  repos/<owner>/<repo>/collaborators --jq length` prints more than 1, or
762
- fails), its default branch is protected, or the push is refused: push a
763
- branch instead, open a pull request, tell them, and stop until it is
764
- merged.
810
+ fails), its default branch `<branch>` is protected (`gh api
811
+ repos/<owner>/<repo>/branches/<branch> --jq .protected` prints `true`,
812
+ `gh api repos/<owner>/<repo>/rules/branches/<branch> --jq length` prints
813
+ more than 0, or either fails), or the push is refused: push a branch
814
+ instead, open a pull request, tell them, and stop until it is merged.
765
815
  - If `git config user.name` or `git config user.email` prints nothing in
766
816
  `D/<repo>`, commit with the name step 1's yes covered:
767
817
  `-c user.name="<their name>" -c user.email="<their noreply address>"`,
@@ -782,6 +832,14 @@ oats onboard D --workspace W --json
782
832
  - **The host must be `confirmed`;** a host that can't be read is a GitHub
783
833
  access problem (step 3). Another member with `cannot-read` is an access
784
834
  question for the setup expert, not a reason to stop.
835
+ - **On Git under 2.45** (step 2; Ubuntu 24.04 ships 2.43), a warning
836
+ that this Git can't keep a partial cache, so OATS fetches whole trees, is
837
+ expected. A recent OATS prints it at most once per command that starts or
838
+ rebuilds caches; an older one prints it once for each repository it
839
+ starts a cache for. Either form is harmless. Don't show it to the person
840
+ as an error, and don't try to fix it now: a Git of 2.45 or later,
841
+ installed later, removes it, and caches already made with whole trees
842
+ stay that way.
785
843
  - **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
786
844
  person whether to use it as it is or to choose another directory.
787
845
 
@@ -806,9 +864,48 @@ needs a clone of its repository at `D/<repo name>`: for an existing
806
864
  workspace whose setup soul is its own, run the `git clone` line
807
865
  `oats onboard` printed for it, if it says it is missing.
808
866
 
809
- **Record the setup expert's harness** on this machine: a package soul names
810
- none, and without this every later check (readiness, harness trust) and the
811
- spawn would use the default, pi:
867
+ **Record the harness for every soul** on this machine: a package soul names
868
+ none, and without this every later check (readiness, harness trust) and
869
+ every spawn would use the default, pi, for `S` and for each soul the setup
870
+ expert or the steward spawns later. `'*'` is every soul without an entry of
871
+ its own, `S` among them, and souls added later that name no harness of
872
+ their own:
873
+
874
+ ```bash
875
+ oats soul launch set '*' --harness <harness> --dir D --plan
876
+ oats soul launch set '*' --harness <harness> --dir D
877
+ ```
878
+
879
+ `'*'` wins over a soul's own `launch:` on this machine. So read
880
+ `oats souls --dir D --json` first, in a new workspace too (a package soul
881
+ may name its harness). For each row whose `launch.declared.harness`
882
+ differs from `<harness>` and whose declared harness is installed and
883
+ logged in here (`claude --version`, `codex --version` or `pi --version`,
884
+ as in step 2), give that soul its own entry with its declared harness, so
885
+ it keeps its choice. A declared harness that isn't installed here stays
886
+ under `'*'`, so the soul can run; name it in the hand-over ("For the
887
+ person, later"). Use the row's `key` (`<package>/<soul>`
888
+ for a package's soul, so the name is never ambiguous), add
889
+ `--model <its model>` only when `launch.declared.model` names one, and plan
890
+ first:
891
+
892
+ ```bash
893
+ oats soul launch set <key> --harness <its harness> --model <its model> --dir D --plan
894
+ oats soul launch set <key> --harness <its harness> --model <its model> --dir D
895
+ ```
896
+
897
+ Check a reviewer soul by its model too, since `'*'` replaces the model as
898
+ well as the harness: where it declares `<harness>` but another model, give
899
+ it its own entry the same way, with `--harness <its harness> --model <its
900
+ model>`. Then its `oats spawn <key> --preview --json --dir D` must show a
901
+ `launch.effective` model from a family other than the developers'. Where
902
+ its declared model can't run here, set one that can, from another family;
903
+ with none, name it in the hand-over ("For the person, later"): its reviews
904
+ share the developers' model.
905
+
906
+ `S` is the exception: it always keeps `<harness>`, the person's choice in
907
+ step 1. When `S` declares another harness, give it its own entry with
908
+ `<harness>` instead:
812
909
 
813
910
  ```bash
814
911
  oats soul launch set S --harness <harness> --dir D --plan
@@ -891,25 +988,54 @@ readiness still reports a problem.
891
988
  whose own agent runs
892
989
  `oats aweb invite --soul <their soul> --label L --json` in their
893
990
  deployment. The answer's `result.token` is the invite token,
894
- passed to the person privately, never by ordinary mail. From oats.aweb
895
- 1.33.1 the answer's `result.awebUrl` is the service URL `U`, no secret,
896
- which the member passes too. When it is `null` or absent, leave
897
- `--service U` out of item 4: the join then takes the service from the
898
- invite, or fails and item 5 stops. This machine's messaging root is
991
+ passed to the person privately, never by ordinary mail. **The token is
992
+ all they pass** when this machine has oats.aweb 1.36.0 or later (the
993
+ `version` of the `oats.aweb` row in the `oats inspect` answer's
994
+ `result.capabilities`, above) and aw 1.36.53 or later (`aw.version` in
995
+ item 1's check): the join reads the team and the service from the
996
+ invite itself. Otherwise the member passes the service URL `U` too:
997
+ from oats.aweb 1.33.1 the answer's `result.awebUrl`, no secret. When it
998
+ is `null` or absent, leave `--service U` out of item 4's labelled form:
999
+ the join then takes the service from the invite, or fails and item 5
1000
+ stops. This machine's messaging root is
899
1001
  `A` = `<workspace>-<this machine's name>` (step 1), with the workspace's
900
1002
  name from step 8: don't ask. Only a hosted team works: if the invite is
901
1003
  refused, or the join says the team is not hosted, stop; the workspace's
902
1004
  owner decides.
903
1005
  4. **Existing workspace: the person joins in their own terminal,** which you
904
- open for them ("How to work"), typing the token at the hidden prompt,
905
- with `D`, `S`, `L`, `A` and `U` filled in:
1006
+ open for them ("How to work"), pasting the token at the hidden prompt,
1007
+ with `D`, `S` and `A` filled in:
1008
+
1009
+ ```text
1010
+ cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --invite-stdin --name A'
1011
+ ```
1012
+
1013
+ Before redeeming anything, it refuses an invite it can't use here: one
1014
+ expired, used up or revoked, one for a team this workspace doesn't name
1015
+ (unless the workspace allows local teams and this machine's own
1016
+ `oats-local.yaml` sets its default team), one whose team's label is
1017
+ already another team here, one for a global identity, or one for a team
1018
+ this machine is already in. The person sees why in the window, and
1019
+ item 5 stops. In that exception, an invite for a team the workspace
1020
+ doesn't name is redeemed instead: this machine joins that team under a
1021
+ label of its own, and item 5 catches it. With an older
1022
+ oats.aweb or aw (item 3), open the labelled form instead, with `L` and
1023
+ `U` filled in too:
906
1024
 
907
1025
  ```text
908
1026
  cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --join L --invite-stdin --name A --service U'
909
1027
  ```
910
1028
 
911
1029
  5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
912
- On `"member": false`, stop and spawn nothing: tell the person the run
1030
+ On `"member": false`, stop and spawn nothing. With `"root": null` after
1031
+ item 4's invite-only form, look first, read-only:
1032
+ `ls -d "D"/.aweb-roots/*/.aw 2>/dev/null`. Nothing printed: the join
1033
+ refused before redeeming anything: ask the person for the `E_SETUP_`
1034
+ code their window shows (a code, no secret), tell them in plain words
1035
+ what it means, and that a new invite is the inviter's to send. A path
1036
+ printed for a label other than `L`: the invite was for that team, and
1037
+ this machine joined it instead: tell them so, and that an invite for
1038
+ `L` is the inviter's to send. Otherwise tell the person the run
913
1039
  left this machine's root outside `L`, with what the check shows, and
914
1040
  don't rerun the signup or the join (you can't see the join's output).
915
1041
  When another machine of the same name may already be in the team, say
@@ -970,7 +1096,8 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
970
1096
 
971
1097
  - Workspace: <workspace> (W), new | existing; deployment directory: D
972
1098
  - Host: <owner>/<repo>, a monorepo | a dedicated host | the first repository
973
- - Setup expert: S, instance <name>, harness <harness>
1099
+ - Setup expert: S, instance <name>, harness <harness> (this machine's
1100
+ harness for every soul without its own)
974
1101
  - Machine found-list only: steward R, address N.aweb.ai/R | local team
975
1102
  identity (<the fallback's reason>)
976
1103
 
@@ -1127,7 +1254,7 @@ and say yes to it in the hand-over below.
1127
1254
  line, with how to change it: "Your agents share aweb's task list; to use
1128
1255
  another tracker later, ask the setup assistant to switch." With a
1129
1256
  tracker: "Your agents use your <GitHub issues | tracker>; the setup
1130
- assistant connects them. Leave aweb's task list empty: one task there
1257
+ assistant offers to connect them. Leave aweb's task list empty: one task there
1131
1258
  opts your whole group in to it. To use aweb's task list instead, ask the
1132
1259
  setup assistant."
1133
1260
 
@@ -1140,6 +1267,10 @@ the setup expert, not in this message. You are done.
1140
1267
 
1141
1268
  ## Never
1142
1269
 
1270
+ - **Run `aw team ensure` when joining an existing workspace.** It is only
1271
+ step 5's, for a new workspace. On a join it doesn't find the teammate's
1272
+ team: it makes a new team of the person's own for the same repository,
1273
+ silently. A join goes through step 9's invite.
1143
1274
  - **Ask for, read, print or store a secret,** or suggest Claude Code's
1144
1275
  `! <command>` for one: its command and output enter your context. If the
1145
1276
  person pastes one anyway, don't repeat it, and tell them to rotate it.
@@ -1,35 +0,0 @@
1
- import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
2
- import { spawnSync } from "node:child_process";
3
- import { homedir } from "node:os";
4
- import { dirname, join } from "node:path";
5
-
6
- const OATS_MOUSE_BLOCK = `# OATS: scroll agent windows normally with a mouse or trackpad.\nset -g mouse on\n`;
7
-
8
- /** Choose the tmux user config without creating a second competing config. */
9
- export function tmuxConfigPath(home = homedir(), env = process.env) {
10
- const legacy = join(home, ".tmux.conf");
11
- const xdg = join(env.XDG_CONFIG_HOME || join(home, ".config"), "tmux", "tmux.conf");
12
- return existsSync(legacy) || !existsSync(xdg) ? legacy : xdg;
13
- }
14
-
15
- /** Whether the selected config explicitly enables tmux mouse support. */
16
- export function tmuxMouseEnabled(text) {
17
- return text.split("\n").some((line) => {
18
- const active = line.replace(/\s+#.*$/, "").trim();
19
- return /^(?:set|set-option)(?:\s+-[a-zA-Z]+)*\s+mouse\s+(?:on|1)\s*$/.test(active);
20
- });
21
- }
22
-
23
- /** Add the setting once and reload a running tmux server when possible. */
24
- export function enableTmuxMouse(configPath = tmuxConfigPath()) {
25
- const before = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
26
- if (tmuxMouseEnabled(before)) return { changed: false, configPath, reloaded: false };
27
-
28
- mkdirSync(dirname(configPath), { recursive: true });
29
- const separator = before.length === 0 || before.endsWith("\n\n") ? "" : before.endsWith("\n") ? "\n" : "\n\n";
30
- appendFileSync(configPath, separator + OATS_MOUSE_BLOCK);
31
-
32
- const server = spawnSync("tmux", ["has-session"], { stdio: "ignore" });
33
- const reloaded = server.status === 0 && spawnSync("tmux", ["source-file", configPath], { stdio: "ignore" }).status === 0;
34
- return { changed: true, configPath, reloaded };
35
- }