chattrs 0.5.0 → 0.7.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.
package/README.md CHANGED
@@ -25,55 +25,193 @@ over TCP, so a script in any language can join too.
25
25
 
26
26
  ## Get running
27
27
 
28
- ### Solo, one machine
28
+ `chattrs exec claude` starts an agent on the swarm. It sets the address
29
+ and the session, then hands the process to the agent. chattrs never hosts
30
+ or supervises the agent. For other launchers (Herdr, tmux, scripts), use
31
+ `chattrs env`, which prints the same settings as `export` lines.
32
+
33
+ `exec` does not put the token in the agent's environment. Each chattrs
34
+ call in the agent reads the token from `config.toml`, as the hooks do. An
35
+ explicit `CHATTRS_TOKEN` in your shell passes through unchanged. If no
36
+ token is found, `exec` prints `chattrs: no token for ADDR; the broker may
37
+ refuse` and still starts the agent.
38
+
39
+ The broker refuses a second live session for the same address (ID-1). The
40
+ refusal shows when the agent's hooks or `watch` connect.
41
+
42
+ #### Start an agent on another host
29
43
 
30
- Install chattrs, then set up the agents once.
44
+ `chattrs exec --host H [--cwd DIR] [--detach] [--session-name NAME] PROGRAM`
45
+ starts the agent on host `H`. It runs the system `ssh`, so `~/.ssh/config`
46
+ aliases work. The remote login shell runs `chattrs exec` there.
31
47
 
32
48
  ```bash
33
- brew install bolu-atx/tap/chattrs # or: npm install -g chattrs
34
- chattrs hooks install # Claude Code and Codex
35
- mkdir -p ~/.claude/skills/chattrs && chattrs skill > ~/.claude/skills/chattrs/SKILL.md
49
+ chattrs exec --host bobox --cwd ~/repo --as w1@bobox --lead lead@mac codex
50
+ chattrs exec --host bobox --cwd ~/repo --detach --as w1@bobox --lead lead@mac codex
36
51
  ```
37
52
 
38
- Open Codex once and run `/hooks` to trust the new hooks. Codex gets the
39
- skill through the session-start hook, which tells it to run `chattrs skill`.
40
- It needs no skill file.
53
+ - chattrs forwards only `--as`, `--lead`, the program, and its arguments.
54
+ It never sends the token, the server, the project, the tags, or any
55
+ `CHATTRS_*` variable. The remote host reads its own config and token.
56
+ - The remote host needs `chattrs` on its login-shell `PATH` and its own
57
+ config and token (`chattrs setup --join`).
58
+ - Without `--detach`, the worker lives only as long as the ssh connection.
59
+ If the launching machine sleeps, loses the network, or closes the
60
+ terminal, the worker stops.
61
+ - With `--detach`, the worker runs in a remote tmux session and chattrs
62
+ returns. The worker lives until it exits or someone kills the session.
63
+ chattrs prints the attach command (`ssh -t H tmux attach -t NAME`) and
64
+ the stop command (`ssh H tmux kill-session -t NAME`). `NAME` defaults to
65
+ the user part of the address, with unsafe characters turned into `-`.
66
+ - tmux is optional. Only `--detach` needs it. If tmux is missing, chattrs
67
+ exits 1 and says so. It never installs tmux, never falls back to a run
68
+ without `--detach`, and never attaches to or kills an existing session.
69
+ - chattrs never watches, kills, or restarts agents.
41
70
 
42
- Now start a lead and a worker in two terminals. Each line sets the
43
- address, a session, and the lead. Nothing else is needed.
71
+ ### Solo, one machine
44
72
 
45
- ```bash
46
- # Terminal 1
47
- eval "$(chattrs env --as lead@mac)" && claude
73
+ Three steps.
48
74
 
49
- # Terminal 2
50
- eval "$(chattrs env --as w1@mac --lead lead@mac)" && codex
51
- ```
75
+ 1. Install chattrs. On macOS: `brew install bolu-atx/tap/chattrs`. For
76
+ npm or cargo, see [Install](#install).
77
+ 2. Set up the agents once:
78
+
79
+ ```bash
80
+ chattrs setup
81
+ ```
82
+
83
+ `setup` finds Claude Code and Codex. For each one it installs the hooks
84
+ and the skill. It writes `~/.config/chattrs/config.toml` only when none
85
+ exists. It is safe to run again. Then follow the printed trust steps:
86
+ open Codex once and run `/hooks` to trust the new hooks. Claude Code may
87
+ ask you to review the hooks.
88
+ 3. Start a lead and a worker in two terminals:
89
+
90
+ ```bash
91
+ # Terminal 1
92
+ chattrs exec --as lead@mac claude
93
+
94
+ # Terminal 2
95
+ chattrs exec --as w1@mac --lead lead@mac codex
96
+ ```
97
+
98
+ Without `--as`, the address is `<program>@<host>`, for example
99
+ `claude@mac`. Arguments after the program go to the program:
100
+ `chattrs exec claude --resume ID`.
52
101
 
53
102
  The first command starts a loopback broker on its own. The session-start
54
- hook tells each agent its address and its lead, and to load the skill. The
55
- hooks deliver messages between tool calls. In Claude Code, the agent also
56
- runs `chattrs watch` under Monitor, so a message wakes it. No special launch
57
- prompt is needed. Ask the lead to send w1 a task, and run `chattrs agents`
58
- to see both agents and their state. An agent shows `online` only while it
59
- runs `chattrs watch`.
103
+ hook tells each agent its address and its lead, and to load the skill.
104
+ Ask the lead to send w1 a task. Run `chattrs agents` to see both agents.
105
+ An agent shows `online` only while it runs `chattrs watch`. Hooks deliver
106
+ messages between tool calls. In Claude Code, the agent runs `chattrs
107
+ watch` under Monitor, so a message wakes it.
60
108
 
61
109
  ### Swarm, several machines
62
110
 
63
- 1. Pick an always-on broker host. Run `chattrs serve` there as a service
64
- ([Run the broker as a service](#run-the-broker-as-a-service)).
65
- 2. Write `tokens.toml` with one token per host
66
- ([Token table](#token-table)). To move an existing swarm to tokens
67
- without breaking clients, follow
68
- [Turning on per-host tokens](#turning-on-per-host-tokens).
69
- 3. On each host, put `server` and `token_file` in
70
- `~/.config/chattrs/config.toml`
71
- ([Set client hosts](#set-client-hosts)).
72
- 4. In each repo, commit a `.chattrs.toml` with `project` and `lead`
73
- ([Environment and config](#environment-and-config)).
74
- 5. Start every agent with the same launch line, with its own address:
75
- `eval "$(chattrs env --as w1@box1)" && codex`
76
- ([Start a worker](#start-a-worker)).
111
+ Five steps. Use a broker host that is always on. A laptop sleeps, and the
112
+ swarm stops. Install and run `chattrs setup` on every host first, as in
113
+ the solo path.
114
+
115
+ 1. On the broker host, issue tokens and write the service unit:
116
+
117
+ ```bash
118
+ chattrs setup --broker --hosts mac,bobox --bind 100.64.0.1 --enable
119
+ ```
120
+
121
+ `--hosts` lists the agent hosts. `--bind` is the tailnet or LAN IP. It
122
+ defaults to the Tailscale IPv4. It never takes `0.0.0.0` or `::`.
123
+ `--enable` starts the service. The command prints one join string for
124
+ each token.
125
+ 2. Copy each host's join string to that host, over a private channel. A
126
+ join string holds a token. Treat it like a password. The broker never
127
+ stores it.
128
+ 3. On each host, run `setup --join` and paste the join strings on stdin.
129
+ End with Ctrl-D. This keeps them out of shell history:
130
+
131
+ ```bash
132
+ chattrs setup --join -
133
+ ```
134
+
135
+ It writes a token file (mode 0600) and one `[tokens]` entry in
136
+ `~/.config/chattrs/config.toml`, and it sets `server`. A host that runs
137
+ agents next to the broker needs this step too. The lead host needs
138
+ the lead's join string as well.
139
+ 4. On each host, check the setup:
140
+
141
+ ```bash
142
+ chattrs doctor --as w1@bobox
143
+ ```
144
+
145
+ Each check prints `ok` or `FAIL` with a fix hint. The command exits 1
146
+ on any failure.
147
+ 5. Launch every agent with its own address:
148
+
149
+ ```bash
150
+ chattrs exec --as lead@mac claude
151
+ chattrs exec --as w1@bobox --lead lead@mac codex
152
+ ```
153
+
154
+ `env --as` exports the address, a new session id, and the server. It does
155
+ not print the token. Each command then reads the token from the `[tokens]`
156
+ entry that matches the address. To set the project for all hosts, commit a
157
+ `.chattrs.toml` in the repo ([Environment and config](#environment-and-config)).
158
+
159
+ ### Several hosts: `setup --broker` and `setup --join` (SETUP-2)
160
+
161
+ Reference for steps 1 to 3 above.
162
+
163
+ ```bash
164
+ chattrs setup --broker --hosts <a,b> [--lead lead@mac] [--projects p1,p2] \
165
+ [--bind <ip>] [--port 4646] [--enable]
166
+ ```
167
+
168
+ It writes `~/.config/chattrs/tokens.toml` (mode 0600) and a systemd user unit
169
+ (`~/.config/systemd/user/chattrs.service`) or a launchd plist
170
+ (`~/Library/LaunchAgents/com.chattrs.broker.plist`). It never overwrites
171
+ either file. It prints the command that starts the service; `--enable` runs
172
+ it. It issues one agent token per host (`*@<host>`), one lead token, and one
173
+ observer token (`tray@*`). The tokens have no `project` line, so they work in
174
+ every project. With `--projects`, it writes one entry per project instead,
175
+ and each token stays inside those projects (the observer still sees all).
176
+ Then it prints one join string for each, `chattrs://<token>@<ip>:<port>?as=<pattern>`. The pattern is
177
+ percent-encoded.
178
+
179
+ `setup --join` also takes a string as an argument. Quote it, but it then
180
+ stays in shell history:
181
+
182
+ ```bash
183
+ chattrs setup --join 'chattrs://TOKEN@100.64.0.1:4646?as=lead%40mac'
184
+ ```
185
+
186
+ `--join` is repeatable, and stdin can carry one string per line. A string
187
+ without `?as=` needs `--as <pattern>` (one string only). Each string writes
188
+ `~/.config/chattrs/<name>.token` (mode 0600). The name is the pattern with
189
+ `@` as `-` and `*` as `any`: `lead@mac` gives `lead-mac.token`,
190
+ `*@bobox` gives `any-bobox.token`. The command sets `server` when it is
191
+ missing, and it refuses a different `server`. It keeps all other lines. It
192
+ refuses a pattern that already has an entry or a file; `--force` replaces
193
+ them. Then it runs the plain `setup`. The project is not in the join
194
+ string; it comes from `.chattrs.toml`, else `default`.
195
+
196
+ ### Check a host: `doctor` (SETUP-3)
197
+
198
+ Reference for step 4 above. Run `chattrs doctor` in the environment of an
199
+ agent (with `CHATTRS_ADDRESS` set, or pass `--as`). It prints one line per
200
+ check, `ok <check>: ...` or `FAIL <check>: ... <fix hint>`, and exits 1 on
201
+ any failure. It checks the config files, the token file each identity uses
202
+ (mode 0600), that the broker accepts a connection, that the broker accepts
203
+ the token for the project and address, the protocol version, the hooks, and
204
+ the skill text. It never prints a token. It writes no file and reads no
205
+ message. The token check sends one normal `hello` as the current address,
206
+ with `CHATTRS_SESSION`, so the broker logs no rejection. It shows the project
207
+ and the broker version from the `welcome`. The `hello` updates the last-seen
208
+ of the current address, so that address looks active to health for a moment.
209
+ This is known and not fixed. Other `[tokens]` identities are listed and not
210
+ probed. Without a current address, doctor checks only that the broker accepts
211
+ a connection and prints a warning. Without `CHATTRS_SESSION`, doctor says
212
+ `hello` without a session and prints a note: use `chattrs env`. A `tray@`
213
+ identity says an observer `hello`. Codex hook trust cannot be detected, so
214
+ doctor always ends with a reminder to trust the hooks in `/hooks` in Codex.
77
215
 
78
216
  ## Install
79
217
 
@@ -90,6 +228,8 @@ build (DIST-1).
90
228
 
91
229
  ## Quick start
92
230
 
231
+ This is the raw CLI on one machine, with no agent. For agents, see [Get running](#get-running).
232
+
93
233
  One machine, no broker terminal. The first command starts a loopback broker
94
234
  on `127.0.0.1:4646`. The broker logs to `chattrs.log` and writes its pid to
95
235
  `chattrs.pid`, both next to the DB. `chattrs stop` ends it.
@@ -127,7 +267,7 @@ that holds `</agent-message` is escaped, so it cannot close the wrapper.
127
267
 
128
268
  ## Commands
129
269
 
130
- Every command except `serve`, `stop`, `skill`, `env`, and `hooks` takes the
270
+ Every command except `serve`, `stop`, `skill`, `env`, `setup`, `doctor`, and `hooks` takes the
131
271
  [common flags](#environment-and-config). Every one except `status`, `projects`,
132
272
  `hook`, and `watch` first prints unread messages, then its own output, and
133
273
  acks them (MSG-5). Announcements never reach an inbox.
@@ -145,7 +285,10 @@ acks them (MSG-5). Announcements never reach an inbox.
145
285
  | `agents [--all] [--json]` | List the agents of the project: online or last seen, state, health, tags. Hides agents offline over 7 days with no traffic since. `--all` shows them. |
146
286
  | `projects [--json]` | List every project with its agent and message counts. Read-only. |
147
287
  | `status working\|idle\|waiting` | Report the own state. Best effort: it never starts a broker, gives up after about 2 s, and always exits 0. |
288
+ | `exec [--as ADDR] [--project P] [--lead ADDR] [--server S] [--tags T] [--host H [--cwd DIR] [--detach [--session-name N]]] [--] PROGRAM [ARGS...]` | Run PROGRAM with the session env that `env` prints. On Unix it replaces the chattrs process. The default address is `<program>@<host>`. It never adds the token to the environment. With `--host` it runs the same command on H over `ssh`, see [Start an agent on another host](#start-an-agent-on-another-host). |
148
289
  | `env --as ADDR [--project P] [--lead ADDR] [--server S] [--tags T] [--token T] [--with-token]` | Print `export` lines for one session: `eval "$(chattrs env --as a@h)"`. It makes a new `CHATTRS_SESSION` on every run. It omits the token unless `--with-token`. |
290
+ | `setup` | Install the hooks and the skill for each agent found (Claude Code, Codex). Write a starter `config.toml` only if missing. Safe to run again. `setup --broker --hosts a,b [...]` prepares a broker host; `setup --join STRING\|-` stores join-string tokens. See [Several hosts](#several-hosts-setup---broker-and-setup---join-setup-2). |
291
+ | `doctor [--as ADDR] [--server S]` | Check config, token files, broker, token, protocol, hooks, and skill. One `ok` or `FAIL` line each; exit 1 on any failure. Read-only. See [Check a host](#check-a-host-doctor-setup-3). |
149
292
  | `hooks install\|remove [--agent claude\|codex\|all] [--project]` | Edit the hook entries in the agent configs. See [Hooks](#hooks-claude-code-and-codex). |
150
293
  | `hook EVENT` | Run as a hook. Reads hook JSON on stdin. Not for direct use. |
151
294
  | `skill` | Print the bundled agent skill. Needs no connection or address. |
@@ -178,6 +321,24 @@ is an error that names the file and line. The repo file holds no secrets: a
178
321
  that holds only the token. On unix it must have mode 0600 or tighter. The
179
322
  token applies when neither `CHATTRS_TOKEN` nor `--token` is set.
180
323
 
324
+ One host can hold several identities (SETUP-4). A `[tokens]` table in the
325
+ user config maps an address or a glob to its own token file:
326
+
327
+ ```toml
328
+ token_file = "/home/me/.config/chattrs/token" # fallback
329
+ [tokens]
330
+ "lead@mac" = "/home/me/.config/chattrs/lead-token"
331
+ "*@mac" = "/home/me/.config/chattrs/mac-token"
332
+ ```
333
+
334
+ The token for an address comes from the first of these that applies:
335
+ `CHATTRS_TOKEN` or `--token`; the `[tokens]` entry that matches the address
336
+ (an exact address beats a glob, and among globs the longest pattern wins);
337
+ the plain `token_file`. The address is `--as`, `--address`, or `--agent`,
338
+ then `CHATTRS_ADDRESS`, then `CHATTRS_AGENT`. `chattrs env --as ADDR
339
+ --with-token` prints the token for ADDR. The table is only in the user
340
+ config, never in `.chattrs.toml`.
341
+
181
342
  ```toml
182
343
  # ~/.config/chattrs/config.toml
183
344
  server = "10.0.0.5:4646"
@@ -214,13 +375,15 @@ Tags come from the latest `hello`. A command run from another shell without
214
375
  ## Teach workers the skill
215
376
 
216
377
  `chattrs skill` prints the worker skill (`skills/chattrs/SKILL.md`).
378
+ `chattrs setup` installs it for Claude Code and Codex. To install it by
379
+ hand:
217
380
 
218
381
  ```bash
219
382
  mkdir -p ~/.claude/skills/chattrs && chattrs skill > ~/.claude/skills/chattrs/SKILL.md
220
383
  ```
221
384
 
222
- For pi, pass that directory with `--skill`. Codex and Muse have no skill
223
- directory. The lead puts `$(chattrs skill)` in the worker's prompt.
385
+ For pi, pass that directory with `--skill`. Muse has no skill directory:
386
+ the lead puts `$(chattrs skill)` in the worker's prompt.
224
387
 
225
388
  Give each worker a unique address. Two agents on one address share an
226
389
  inbox. There is no default agent name.
@@ -248,15 +411,18 @@ holder every project and every address. Use it for a quick test only.
248
411
  ### Keep the database
249
412
 
250
413
  Put `CHATTRS_DB` (or `--db`) on persistent disk. The broker never deletes a
251
- message, so the database is the swarm's history. Back it up with SQLite,
252
- never with `cp` on a live database:
414
+ message, so the database is the swarm's history. Back it up with
415
+ `chattrs backup`, never with `cp` on a live database. It works while the
416
+ broker runs and refuses to replace a file unless you pass `--force`:
253
417
 
254
418
  ```bash
255
- sqlite3 <db> ".backup <file>"
419
+ chattrs backup <file> [--db <db>] [--force]
256
420
  ```
257
421
 
258
422
  ### Run the broker as a service
259
423
 
424
+ `chattrs setup --broker` writes these units for you ([Get running](#get-running)). Use this section to write them by hand.
425
+
260
426
  Linux: put a `systemd --user` unit in
261
427
  `~/.config/systemd/user/chattrs.service`.
262
428
 
@@ -315,6 +481,8 @@ for an unattended Mac.
315
481
 
316
482
  ### Set client hosts
317
483
 
484
+ `chattrs setup --join` does this for you ([Get running](#get-running)). Use this section to edit the config by hand.
485
+
318
486
  On every client host, set the broker address and the token file in the user
319
487
  config (see [Environment and config](#environment-and-config)):
320
488
 
@@ -330,17 +498,28 @@ second, auto-started broker, and that agent then joins a different swarm.
330
498
 
331
499
  ### Start a worker
332
500
 
333
- The lead starts each worker over ssh in a detached tmux session. The worker
334
- needs no flags. The host config has the server and token file. The repo's
335
- `.chattrs.toml` has the project and lead. The address, session, project,
336
- and lead exist only in the launch line:
501
+ The lead starts each worker with `chattrs exec --host`. The worker needs no
502
+ flags. The host config has the server and token file. The project is the
503
+ repo name, and the repo's `.chattrs.toml` can set the lead:
337
504
 
338
505
  ```bash
339
- ssh <host> 'tmux new -d -s w1 '"'"'eval "$(chattrs env --as worker1@<host>)"; exec claude "Your address is worker1@<host>. Your lead is opus@mac. Run chattrs watch under the Monitor tool now."'"'"''
506
+ chattrs exec --host <host> --cwd ~/repo --detach --as worker1@<host> --lead opus@mac claude "Your address is worker1@<host>. Your lead is opus@mac. Run chattrs watch under the Monitor tool now."
340
507
  ```
341
508
 
509
+ `--detach` starts the worker in a tmux session on the host and prints how
510
+ to attach and stop it. Without `--detach`, the worker lives only as long as
511
+ the ssh connection: if the launching machine sleeps, loses network, or
512
+ closes the terminal, the worker stops.
513
+
342
514
  On the host itself:
343
515
 
516
+ ```bash
517
+ chattrs exec --as worker1@box claude "..."
518
+ ```
519
+
520
+ For other launchers (Herdr, tmux, scripts), `chattrs env` prints the same
521
+ settings as shell exports:
522
+
344
523
  ```bash
345
524
  tmux new -d -s w1 'eval "$(chattrs env --as worker1@box)"; exec claude "..."'
346
525
  ```
@@ -385,43 +564,50 @@ Run this once on a new swarm.
385
564
 
386
565
  ### Token table
387
566
 
388
- Meets SEC-4. A token table gives each token a project, an address pattern,
389
- and a role. Start the broker with `serve --tokens <path>` or
567
+ Meets SEC-4. A token table gives each token an address pattern and a role.
568
+ A token works in every project. An optional `project` line limits it to one
569
+ project. Start the broker with `serve --tokens <path>` or
390
570
  `CHATTRS_TOKENS`. The file is TOML. The broker refuses to start when its
391
571
  mode is wider than 0600 (unix). Make each token with `openssl rand -hex 32`.
392
572
 
393
573
  ```toml
394
- # The lead of project alpha. Only a lead token can claim this address.
574
+ # The lead. Only a lead token can claim this address, in any project.
395
575
  [[token]]
396
576
  token = "<64 hex characters>"
397
- project = "alpha"
398
577
  addr = "lead@box1"
399
578
  role = "lead"
400
579
 
401
- # Any worker on box1, in alpha only.
580
+ # Any worker on box1, in every project.
402
581
  [[token]]
403
582
  token = "<64 hex characters>"
404
- project = "alpha"
405
583
  addr = "*@box1"
406
584
  role = "agent"
407
585
 
586
+ # A worker on box2, walled into project alpha.
587
+ [[token]]
588
+ token = "<64 hex characters>"
589
+ project = "alpha"
590
+ addr = "*@box2"
591
+ role = "agent"
592
+
408
593
  # A read-only viewer that sees every project.
409
594
  [[token]]
410
595
  token = "<64 hex characters>"
411
- project = "*"
412
596
  addr = "tray@mac"
413
597
  role = "observer"
414
598
  ```
415
599
 
416
600
  The parser reads a small subset of TOML: blank lines, `#` comments,
417
601
  `[[token]]` headers, and `key = "value"` lines (double quotes, no escapes).
418
- The keys `token`, `project`, `addr`, and `role` are required, once each.
419
- Any other line, an unknown key, a bad value, or a repeated token stops the
420
- broker with an error that names the line. A lead who leads several projects
421
- uses one token and lists it once per project. One token twice in one
422
- project is refused.
423
-
424
- - `project` is a project name, or `"*"` for `observer` entries only.
602
+ The keys `token`, `addr`, and `role` are required. `project` is optional.
603
+ Each key appears once per entry. Any other line, an unknown key, or a bad
604
+ value stops the broker with an error that names the line. A repeated token
605
+ stops it too, unless every copy names a different project. A lead who
606
+ leads several projects can use one entry with no `project`, or one token
607
+ listed once per project.
608
+
609
+ - `project` is a project name. With no `project`, the token works in every
610
+ project. `"*"` means the same, for `observer` entries only (the old form).
425
611
  - `addr` is an exact address, or a pattern where `*` matches any run of
426
612
  characters, such as `*@box1`.
427
613
  - `role` is `lead`, `agent`, or `observer`.
@@ -431,9 +617,10 @@ time, then checks the hello:
431
617
 
432
618
  - No entry matches: `bad_token`. The broker closes the connection.
433
619
  - The project or address does not fit the entry, or a role rule fails:
434
- `forbidden`.
620
+ `forbidden`. The project check applies only to an entry with a `project`.
435
621
  - Lead rule: only a `lead` entry can claim an address that a `lead` entry
436
- names exactly in that project.
622
+ names exactly. This holds in every project, whether or not that entry
623
+ has a `project`.
437
624
  - Observer rule: an `observer` entry works only with an observer hello. An
438
625
  `agent` entry cannot send an observer hello.
439
626
 
@@ -455,12 +642,14 @@ Rules:
455
642
 
456
643
  #### Turning on per-host tokens
457
644
 
645
+ This is for a swarm that already runs on the shared token. A new swarm uses `chattrs setup --broker` instead.
646
+
458
647
  Once a tokens file exists, the broker refuses the shared token. Switching
459
648
  everything at once breaks every client at the same moment. Use two phases.
460
649
 
461
650
  Phase 1: a plain upgrade.
462
651
 
463
- 1. Back up the database: `sqlite3 <db> ".backup <file>"`.
652
+ 1. Back up the database: `chattrs backup <file> --db <db>`.
464
653
  2. Upgrade the broker. Start it with no tokens file. Legacy mode stays on.
465
654
  3. Check that workers and viewers still connect.
466
655
 
@@ -489,9 +678,23 @@ another project lands in the sender's project, with `known:false`. The same
489
678
  address in two projects is two agents (NS-1). A client with no project uses
490
679
  `default`.
491
680
 
492
- Set `CHATTRS_PROJECT` in the launch environment, with an explicit name.
493
- Never derive it from the directory name: a renamed or second checkout would
494
- split or merge swarms.
681
+ A client picks its project in this order. The first match wins:
682
+
683
+ 1. `CHATTRS_PROJECT` or `--project`.
684
+ 2. `project` in `.chattrs.toml` or `~/.config/chattrs/config.toml`.
685
+ 3. The repo name, when the directory is inside a git repo.
686
+ 4. `default`.
687
+
688
+ The repo name is the last part of the `origin` URL, without `.git`. With no
689
+ `origin`, it is the name of the directory that holds the repo. A worktree
690
+ has the same name as its main repo. The name is lowercase, and every
691
+ character outside `a-z` and `0-9` becomes `-`. `chattrs doctor` and
692
+ `chattrs env` print the project and its source.
693
+
694
+ Upgrade note: a session inside a repo now joins the repo project, not
695
+ `default`. A token table that allows only `default` rejects it. Add the repo
696
+ project to `tokens.toml`, or pin `project` in `.chattrs.toml`. Doctor then
697
+ says `token not valid for project <name> (derived from git)`.
495
698
 
496
699
  ```bash
497
700
  export CHATTRS_PROJECT=alpha
@@ -589,7 +792,7 @@ Client to broker:
589
792
  Broker to client:
590
793
 
591
794
  ```json
592
- {"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha"}
795
+ {"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha", "version":"0.6.0"}
593
796
  {"type":"sent", "id":12} // optional "known":false: `to` never said hello
594
797
  {"type":"inbox", "messages":[
595
798
  {"id":12,"from":"codex@box1","to":"opus@mac",
@@ -623,6 +826,9 @@ carries a token, loopback too. Optional `hello` fields:
623
826
  15 minutes as `unknown` (MON-4). `chattrs status` sends such a `hello`.
624
827
  - `observer`: see [Monitoring](#monitoring-api-observer).
625
828
 
829
+ `welcome` carries `"version"`, the broker's crate version. It is optional:
830
+ an older broker omits it, and an older client ignores it. `doctor` shows it.
831
+
626
832
  `welcome` may carry `"watching":true` when the address already has a live
627
833
  inbox `watch`. The `watch` command then warns once on stderr and keeps
628
834
  going.
@@ -19,7 +19,7 @@
19
19
  "hasInstallScript": true,
20
20
  "license": "MIT",
21
21
  "name": "chattrs",
22
- "version": "0.5.0"
22
+ "version": "0.7.0"
23
23
  },
24
24
  "node_modules/detect-libc": {
25
25
  "engines": {
@@ -48,5 +48,5 @@
48
48
  }
49
49
  },
50
50
  "requires": true,
51
- "version": "0.5.0"
51
+ "version": "0.7.0"
52
52
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "artifactDownloadUrls": [
3
- "https://github.com/bolu-atx/chattrs/releases/download/v0.5.0"
3
+ "https://github.com/bolu-atx/chattrs/releases/download/v0.7.0"
4
4
  ],
5
5
  "bin": {
6
6
  "chattrs": "run-chattrs.js"
@@ -79,7 +79,7 @@
79
79
  "zipExt": ".tar.xz"
80
80
  }
81
81
  },
82
- "version": "0.5.0",
82
+ "version": "0.7.0",
83
83
  "volta": {
84
84
  "node": "18.14.1",
85
85
  "npm": "9.5.0"