@awebai/oats 0.69.12 → 0.69.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. package/lib/tmux-config.mjs +0 -35
@@ -0,0 +1,204 @@
1
+ #!/usr/bin/python3 -I
2
+ """oats-login-receive: forced-command receiver for harness credentials (oats-project/oats#1786, OATS 9b1ed301).
3
+
4
+ Installed root-owned 0755 at /usr/local/sbin/oats-login-receive and reached ONLY through a dedicated key in root's
5
+ authorized_keys: restrict,command="/usr/local/sbin/oats-login-receive" <key>
6
+ SSH_ORIGINAL_COMMAND is "install|remove|status <harness> <name>"; for install the credential comes on stdin.
7
+ Answers one JSON line {ok, harness, name, fingerprint, replacedAt} (plus "error" when ok is false).
8
+ Never prints, logs or echoes the credential; the fingerprint is a sha256 prefix.
9
+
10
+ The destination comes from the root-owned config (/etc/oats-login/receiver.json), never from the caller:
11
+ {"teams": {"<name>": {"group": "<group that may read>", "harnesses": ["claude", ...],
12
+ "path": "/srv/oats-team/{name}/login/{harness}-token"}}} (path optional; that is the default)
13
+ The file is root:<group> 0440, written atomically; its parent directories are created root-owned (0750 for the login dir).
14
+ """
15
+ import datetime, grp, hashlib, json, os, re, stat, sys, syslog
16
+
17
+ CONFIG = "/etc/oats-login/receiver.json"
18
+ DEFAULT_PATH = "/srv/oats-team/{name}/login/{harness}-token"
19
+ HARNESSES = {"claude", "codex", "pi", "opencode"}
20
+ NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,62}$")
21
+ MAX_BYTES = 65536
22
+
23
+
24
+ class Refused(Exception):
25
+ pass
26
+
27
+
28
+ def now():
29
+ return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
30
+
31
+
32
+ def fingerprint(data):
33
+ return "sha256:" + hashlib.sha256(data).hexdigest()[:16]
34
+
35
+
36
+ def root_owned_not_writable(path, want_dir):
37
+ st = os.lstat(path)
38
+ if stat.S_ISLNK(st.st_mode):
39
+ raise Refused(f"{path} is a symlink")
40
+ if want_dir and not stat.S_ISDIR(st.st_mode) or not want_dir and not stat.S_ISREG(st.st_mode):
41
+ raise Refused(f"{path} has the wrong type")
42
+ if st.st_uid != 0 or st.st_mode & 0o022:
43
+ raise Refused(f"{path} is not root-owned or is group/other-writable")
44
+
45
+
46
+ def load_config(path=CONFIG):
47
+ try:
48
+ root_owned_not_writable(path, want_dir=False)
49
+ root_owned_not_writable(os.path.dirname(path), want_dir=True)
50
+ with open(path) as f:
51
+ cfg = json.load(f)
52
+ except FileNotFoundError:
53
+ raise Refused("receiver config absent")
54
+ except (ValueError, OSError) as e:
55
+ raise Refused(f"receiver config unreadable: {type(e).__name__}")
56
+ if not isinstance(cfg.get("teams"), dict):
57
+ raise Refused("receiver config has no teams")
58
+ return cfg
59
+
60
+
61
+ def parse_command(raw):
62
+ parts = (raw or "").split()
63
+ if len(parts) != 3:
64
+ raise Refused("usage: install|remove|status <harness> <name>")
65
+ action, harness, name = parts
66
+ if action not in ("install", "remove", "status"):
67
+ raise Refused("unknown action")
68
+ if harness not in HARNESSES:
69
+ raise Refused("unknown harness")
70
+ if not NAME_RE.match(name):
71
+ raise Refused("bad name")
72
+ return action, harness, name
73
+
74
+
75
+ def destination(cfg, harness, name):
76
+ team = cfg["teams"].get(name)
77
+ if not isinstance(team, dict):
78
+ raise Refused("name not configured on this host")
79
+ hs = team.get("harnesses")
80
+ if not isinstance(hs, list) or harness not in hs:
81
+ raise Refused("harness not enabled for this name")
82
+ try:
83
+ gid = grp.getgrnam(team["group"]).gr_gid
84
+ except (KeyError, TypeError):
85
+ raise Refused("configured group absent")
86
+ path = (team.get("path") or DEFAULT_PATH).format(name=name, harness=harness)
87
+ if not os.path.isabs(path) or ".." in path.split("/"):
88
+ raise Refused("configured path is not absolute and normalized")
89
+ return path, gid
90
+
91
+
92
+ def ensure_parents(path, gid):
93
+ """Create missing parents root-owned; the login dir itself root:<group> 0750. Existing ones must be root-owned, not writable by others, no symlinks."""
94
+ login_dir = os.path.dirname(path)
95
+ parts = login_dir.strip("/").split("/")
96
+ cur = "/"
97
+ for i, p in enumerate(parts):
98
+ cur = os.path.join(cur, p)
99
+ last = i == len(parts) - 1
100
+ if not os.path.lexists(cur):
101
+ os.mkdir(cur, 0o750 if last else 0o755)
102
+ os.chown(cur, 0, gid if last else 0)
103
+ os.chmod(cur, 0o750 if last else 0o755)
104
+ root_owned_not_writable(cur, want_dir=True)
105
+ return login_dir
106
+
107
+
108
+ def read_credential(stream):
109
+ data = stream.read(MAX_BYTES + 1)
110
+ if len(data) > MAX_BYTES:
111
+ raise Refused("credential too large")
112
+ data = data.strip()
113
+ if not data:
114
+ raise Refused("empty credential")
115
+ if b"\0" in data:
116
+ raise Refused("credential contains NUL")
117
+ return data
118
+
119
+
120
+ def check_shape(harness, data):
121
+ # Shape only, never the value. Claude setup-token tokens are one line with the sk-ant-oat prefix.
122
+ if harness == "claude" and (not data.startswith(b"sk-ant-oat") or b"\n" in data or len(data) > 512):
123
+ raise Refused("not a claude setup-token")
124
+
125
+
126
+ def install(path, gid, data):
127
+ login_dir = ensure_parents(path, gid)
128
+ if os.path.lexists(path):
129
+ root_owned_not_writable(path, want_dir=False)
130
+ tmp = os.path.join(login_dir, f".{os.path.basename(path)}.{os.getpid()}.new")
131
+ fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o400)
132
+ try:
133
+ try:
134
+ os.fchown(fd, 0, gid)
135
+ os.fchmod(fd, 0o440)
136
+ os.write(fd, data + b"\n")
137
+ os.fsync(fd)
138
+ finally:
139
+ os.close(fd)
140
+ os.rename(tmp, path)
141
+ except BaseException:
142
+ try:
143
+ os.unlink(tmp)
144
+ except OSError:
145
+ pass
146
+ raise
147
+ dfd = os.open(login_dir, os.O_RDONLY | os.O_DIRECTORY)
148
+ try:
149
+ os.fsync(dfd)
150
+ finally:
151
+ os.close(dfd)
152
+
153
+
154
+ def run(raw_command, stdin, config_path=CONFIG):
155
+ out = {"ok": False, "harness": None, "name": None, "fingerprint": None, "replacedAt": None}
156
+ try:
157
+ action, harness, name = parse_command(raw_command)
158
+ out.update(harness=harness, name=name)
159
+ path, gid = destination(load_config(config_path), harness, name)
160
+ if action == "install":
161
+ data = read_credential(stdin)
162
+ check_shape(harness, data)
163
+ install(path, gid, data)
164
+ out.update(ok=True, fingerprint=fingerprint(data), replacedAt=now())
165
+ elif action == "remove":
166
+ if os.path.lexists(path):
167
+ root_owned_not_writable(path, want_dir=False)
168
+ os.unlink(path)
169
+ out.update(ok=True, replacedAt=now())
170
+ else: # status
171
+ if not os.path.lexists(path):
172
+ raise Refused("no credential installed")
173
+ root_owned_not_writable(path, want_dir=False)
174
+ with open(path, "rb") as f:
175
+ data = f.read().strip()
176
+ st = os.lstat(path)
177
+ out.update(ok=True, fingerprint=fingerprint(data),
178
+ replacedAt=datetime.datetime.fromtimestamp(st.st_mtime, datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"))
179
+ except Refused as e:
180
+ out["error"] = str(e)
181
+ except OSError as e:
182
+ out["error"] = f"io error: {type(e).__name__}"
183
+ except Exception as e: # never leave the caller without a JSON line and a syslog record
184
+ out["error"] = f"internal error: {type(e).__name__}"
185
+ return out
186
+
187
+
188
+ def main():
189
+ os.umask(0o077)
190
+ out = run(os.environ.get("SSH_ORIGINAL_COMMAND", ""), sys.stdin.buffer)
191
+ syslog.openlog("oats-login-receive", 0, syslog.LOG_AUTH)
192
+ # Log only the VALIDATED action (never the raw first token: a client that puts the credential in the command
193
+ # line must not write it into the auth log).
194
+ first = (os.environ.get("SSH_ORIGINAL_COMMAND", "").split() or ["-"])[0]
195
+ action = first if first in ("install", "remove", "status") else "-"
196
+ syslog.syslog(syslog.LOG_NOTICE, "ok=%s action=%s harness=%s name=%s fingerprint=%s client=%s" % (
197
+ out["ok"], action, out["harness"], out["name"],
198
+ out["fingerprint"], (os.environ.get("SSH_CLIENT", "-").split() or ["-"])[0]))
199
+ print(json.dumps(out))
200
+ return 0 if out["ok"] else 1
201
+
202
+
203
+ if __name__ == "__main__":
204
+ sys.exit(main())
@@ -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
@@ -352,7 +353,7 @@ On Linux x64, also check the Desktop's system libraries, ALSA and FUSE 2
352
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
353
354
  ```
354
355
 
355
- - **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
356
+ - **Versions:** Node 22.5 or later; Git 2.45 or later recommended (partial
356
357
  caches; older Git works with whole-tree fetches); `gh` 2.49 or later
357
358
  (step 3 uses `gh attestation`).
358
359
  - **The harness** they chose must be installed and logged in (`claude
@@ -399,18 +400,26 @@ for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -
399
400
  whole-tree fetches, and go on.
400
401
  - **npm's global folder** must be writable for step 4's installs
401
402
  (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node under
402
- `/usr`, as NodeSource installs it), set a per-user prefix,
403
- `npm config set prefix ~/.local`, as step 1's list said (when Node will
404
- come from NodeSource, the list names the per-user folder and its PATH
405
- line). Then start each later command of yours with
406
- `export PATH="$HOME/.local/bin:$PATH"`, and add that line to their shell's
407
- startup file yourself, so their own terminal finds `oats` too, and tell
408
- them: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc` (for fish,
409
- `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`):
410
408
 
411
- ```bash
412
- 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"
413
- ```
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"`.
414
423
  - **Windows** is not supported.
415
424
 
416
425
  ## 3. Log in to GitHub
@@ -489,9 +498,21 @@ file: `oats-desktop-V-linux-x86_64.AppImage` on Linux x64,
489
498
  checksum and the release's attestation all pass:
490
499
 
491
500
  ```bash
492
- 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 & }
493
502
  ```
494
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
+
495
516
  Write the folder it prints in as `<W>` in step 4.
496
517
 
497
518
  ## 4. Install OATS Desktop, the CLI and the messaging CLI
@@ -512,7 +533,7 @@ installed CLI's catalog:
512
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"
513
534
  ```
514
535
 
515
- It prints the two refs, for example `oats-framework/v1.22.1 v1.37.0`. If the
536
+ It prints the two refs, for example `oats-framework/v1.23.0 v1.37.0`. If the
516
537
  framework's version (after the `/`) is below `1.19.0`, or with aweb
517
538
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
518
539
  skill: stop, and tell the person to wait for the next OATS
@@ -744,7 +765,7 @@ name: acme
744
765
  members:
745
766
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
746
767
  packages:
747
- oats.framework: v1.22.1 # the installed CLI's catalog versions (below)
768
+ oats.framework: v1.23.0 # the installed CLI's catalog versions (below)
748
769
  oats.aweb: v1.37.0 # messaging: agent identities, mail and chat
749
770
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
750
771
  defaults:
@@ -811,6 +832,14 @@ oats onboard D --workspace W --json
811
832
  - **The host must be `confirmed`;** a host that can't be read is a GitHub
812
833
  access problem (step 3). Another member with `cannot-read` is an access
813
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.
814
843
  - **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
815
844
  person whether to use it as it is or to choose another directory.
816
845
 
@@ -865,6 +894,15 @@ oats soul launch set <key> --harness <its harness> --model <its model> --dir D -
865
894
  oats soul launch set <key> --harness <its harness> --model <its model> --dir D
866
895
  ```
867
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
+
868
906
  `S` is the exception: it always keeps `<harness>`, the person's choice in
869
907
  step 1. When `S` declares another harness, give it its own entry with
870
908
  `<harness>` instead:
@@ -950,25 +988,54 @@ readiness still reports a problem.
950
988
  whose own agent runs
951
989
  `oats aweb invite --soul <their soul> --label L --json` in their
952
990
  deployment. The answer's `result.token` is the invite token,
953
- passed to the person privately, never by ordinary mail. From oats.aweb
954
- 1.33.1 the answer's `result.awebUrl` is the service URL `U`, no secret,
955
- which the member passes too. When it is `null` or absent, leave
956
- `--service U` out of item 4: the join then takes the service from the
957
- 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
958
1001
  `A` = `<workspace>-<this machine's name>` (step 1), with the workspace's
959
1002
  name from step 8: don't ask. Only a hosted team works: if the invite is
960
1003
  refused, or the join says the team is not hosted, stop; the workspace's
961
1004
  owner decides.
962
1005
  4. **Existing workspace: the person joins in their own terminal,** which you
963
- open for them ("How to work"), typing the token at the hidden prompt,
964
- 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:
965
1024
 
966
1025
  ```text
967
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'
968
1027
  ```
969
1028
 
970
1029
  5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
971
- 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
972
1039
  left this machine's root outside `L`, with what the check shows, and
973
1040
  don't rerun the signup or the join (you can't see the join's output).
974
1041
  When another machine of the same name may already be in the team, say
@@ -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
- }