turno-cli 0.1.1 → 0.2.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 (104) hide show
  1. package/CHANGELOG.md +284 -0
  2. package/README.md +120 -53
  3. package/dist/accounts/audit.js +137 -7
  4. package/dist/accounts/builtin.js +68 -21
  5. package/dist/accounts/delegate.js +176 -35
  6. package/dist/accounts/policy.js +77 -0
  7. package/dist/accounts/registry.js +37 -21
  8. package/dist/agents/adapter.js +7 -0
  9. package/dist/agents/claude.js +195 -0
  10. package/dist/agents/codex.js +98 -0
  11. package/dist/agents/copilot.js +39 -0
  12. package/dist/agents/cursor.js +41 -0
  13. package/dist/agents/index.js +26 -86
  14. package/dist/agents/snippets.js +7 -4
  15. package/dist/cli/args.js +19 -4
  16. package/dist/cli/commands/accounts.js +96 -51
  17. package/dist/cli/commands/auto.js +82 -32
  18. package/dist/cli/commands/browser.js +216 -135
  19. package/dist/cli/commands/complete.js +2 -1
  20. package/dist/cli/commands/completion.js +4 -2
  21. package/dist/cli/commands/config.js +103 -18
  22. package/dist/cli/commands/demo.js +292 -0
  23. package/dist/cli/commands/doctor.js +387 -119
  24. package/dist/cli/commands/handoff.js +33 -22
  25. package/dist/cli/commands/identity.js +101 -50
  26. package/dist/cli/commands/init.js +616 -0
  27. package/dist/cli/commands/limit.js +25 -13
  28. package/dist/cli/commands/mcp-oauth.js +194 -0
  29. package/dist/cli/commands/mcp-observe.js +434 -0
  30. package/dist/cli/commands/mcp.js +653 -185
  31. package/dist/cli/commands/mcpd.js +323 -75
  32. package/dist/cli/commands/migrate.js +6 -4
  33. package/dist/cli/commands/open.js +92 -27
  34. package/dist/cli/commands/profile.js +205 -69
  35. package/dist/cli/commands/resolve.js +6 -2
  36. package/dist/cli/commands/run.js +15 -5
  37. package/dist/cli/commands/secret.js +61 -42
  38. package/dist/cli/commands/session.js +2 -2
  39. package/dist/cli/commands/sessions.js +42 -12
  40. package/dist/cli/commands/setup.js +136 -158
  41. package/dist/cli/commands/status.js +172 -41
  42. package/dist/cli/commands/statusline.js +305 -113
  43. package/dist/cli/commands/ui.js +64 -66
  44. package/dist/cli/commands/undo.js +161 -18
  45. package/dist/cli/commands/uninstall.js +462 -0
  46. package/dist/cli/commands/upgrade.js +75 -19
  47. package/dist/cli/commands/usage.js +117 -44
  48. package/dist/cli/commands/version.js +7 -5
  49. package/dist/cli/commands/which.js +7 -24
  50. package/dist/cli/compile-cache.js +32 -0
  51. package/dist/cli/group.js +10 -10
  52. package/dist/cli/help.js +57 -0
  53. package/dist/cli/highlight.js +236 -0
  54. package/dist/cli/io.js +170 -1
  55. package/dist/cli/launch.js +21 -37
  56. package/dist/cli/launchers.js +145 -94
  57. package/dist/cli/main.js +163 -27
  58. package/dist/cli/picker.js +447 -0
  59. package/dist/cli/registry.js +42 -5
  60. package/dist/cli/security.js +539 -0
  61. package/dist/cli/style.js +281 -0
  62. package/dist/core/config.js +145 -23
  63. package/dist/core/exhausted.js +6 -8
  64. package/dist/core/fsutil.js +47 -0
  65. package/dist/core/journal.js +281 -11
  66. package/dist/core/manifest.js +126 -6
  67. package/dist/core/paths.js +114 -7
  68. package/dist/core/profiles.js +139 -9
  69. package/dist/core/resolve.js +129 -23
  70. package/dist/core/secrets.js +215 -20
  71. package/dist/core/sessions.js +13 -20
  72. package/dist/core/update.js +18 -8
  73. package/dist/demo/server.js +34 -0
  74. package/dist/mcpd/cache.js +18 -4
  75. package/dist/mcpd/calllog.js +253 -0
  76. package/dist/mcpd/client-names.js +51 -0
  77. package/dist/mcpd/connectors.js +148 -17
  78. package/dist/mcpd/daemon.js +452 -116
  79. package/dist/mcpd/folder-sets.js +39 -0
  80. package/dist/mcpd/gateway.js +441 -47
  81. package/dist/mcpd/health.js +269 -0
  82. package/dist/mcpd/importer.js +356 -36
  83. package/dist/mcpd/instances.js +425 -65
  84. package/dist/mcpd/jsonrpc.js +8 -0
  85. package/dist/mcpd/launchd.js +65 -48
  86. package/dist/mcpd/modern.js +648 -0
  87. package/dist/mcpd/oauth.js +791 -0
  88. package/dist/mcpd/peerpid.js +122 -6
  89. package/dist/mcpd/pressure.js +85 -0
  90. package/dist/mcpd/rss.js +151 -0
  91. package/dist/mcpd/service.js +167 -0
  92. package/dist/mcpd/state.js +183 -0
  93. package/dist/mcpd/sync.js +55 -80
  94. package/dist/mcpd/systemd.js +80 -0
  95. package/dist/mcpd/tokens.js +89 -0
  96. package/dist/mcpd/upstream.js +154 -44
  97. package/dist/statusline/cost.js +154 -44
  98. package/dist/statusline/input.js +66 -0
  99. package/dist/statusline/render.js +9 -3
  100. package/dist/ui/fonts.js +8 -3
  101. package/dist/ui/settings.js +27 -15
  102. package/npm-shrinkwrap.json +1093 -0
  103. package/package.json +6 -6
  104. package/dist/cli/commands/available.js +0 -18
package/README.md CHANGED
@@ -27,37 +27,34 @@ only when a tool is called, behind one local gateway that every session of every
27
27
  ([benchmark](https://github.com/wimo-dev/turno/blob/main/BENCHMARKS.md)). It also gives each folder its own account, so work repositories
28
28
  open with your work login and everything else with your personal one.
29
29
 
30
- ![turno: profiles for two agents, one gateway, the status line](https://raw.githubusercontent.com/wimo-dev/turno/main/docs/assets/demo.gif)
30
+ ![turno demo: two profiles, one gateway, the status line, the picker and turno doctor, in a throwaway HOME](https://raw.githubusercontent.com/wimo-dev/turno/main/docs/assets/demo.gif)
31
31
 
32
32
  ## Install
33
33
 
34
34
  ```sh
35
- npx turno-cli@latest doctor # try it without installing: checks your agents and config
35
+ npx turno-cli demo # try it first, in a throwaway HOME; your own setup is not touched
36
36
  npm install --global turno-cli # macOS or Linux, Node 22.11+
37
37
  brew tap wimo-dev/turno && brew trust wimo-dev/turno && brew install turno # or Homebrew
38
38
  ```
39
39
 
40
- The npm package is `turno-cli`; the command it installs is `turno`.
41
-
42
- Then move your MCP servers behind the gateway:
43
-
44
- ```sh
45
- turno mcp import --move-secrets --write # mcp.toml from the servers you already have
46
- turno mcp daemon start # the gateway, kept alive by launchd
47
- turno mcp sync # point every agent profile at it
48
- ```
49
-
50
- Nothing leaves your machine: no account, no telemetry, no proxy for model traffic.
40
+ The npm package is `turno-cli`; the command it installs is `turno`. It runs no install scripts
41
+ and ships an `npm-shrinkwrap.json`, so you get exactly the dependency versions that were tested
42
+ (CI checks both). Nothing leaves your machine: no account, no telemetry, no proxy for model
43
+ traffic.
51
44
 
52
45
  ## What it does
53
46
 
54
47
  - **One MCP gateway for every session.** `mcpd` listens on `127.0.0.1`, answers `initialize` and
55
48
  the tool lists from a cache, starts a server the first time one of its tools is called, shares
56
49
  that process between sessions where it is safe (`shared`, `project` or `session` scope) and
57
- stops it when idle. Secrets live in the macOS Keychain, not in agent configs.
58
- - **An account per folder.** `turno profile assign ~/code/acme work` and every agent you open in
59
- that repository uses your work login; `turno auto` picks it, and `turno status` shows who is
60
- logged in where. Conversations, skills and settings stay shared between your Claude Code
50
+ stops it when idle, sooner when memory is low. It speaks MCP 2025-11-25 and 2026-07-28 on the
51
+ same endpoint, logs in to OAuth remote servers once per account (`turno mcp login`), and
52
+ `turno mcp log`, `top` and `savings` show its calls, memory and saving. Secrets live in the
53
+ macOS Keychain or the Linux Secret Service, not in agent configs. See [docs/mcp.md](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md).
54
+ - **Per-folder accounts and MCP server sets.** `turno profile assign ~/code/acme work` and every
55
+ agent you open in that repository uses your work login; `turno auto` picks it, and
56
+ `turno status` shows who is logged in where. The same folder rule can choose which MCP servers
57
+ sessions there see. Conversations, skills and settings stay shared between your Claude Code
61
58
  profiles, so `turno work --resume <id>` continues a session started with another account.
62
59
  - **Four agents, one setup.** The same profiles, folder rules and gateway for:
63
60
 
@@ -72,24 +69,42 @@ Nothing leaves your machine: no account, no telemetry, no proxy for model traffi
72
69
  `turno mcp config --agent <name>` prints their entries. See [docs/agents.md](https://github.com/wimo-dev/turno/blob/main/docs/agents.md).
73
70
  - **A status line** for Claude Code with the account, its 5 h and weekly usage, context, branch
74
71
  and cost, with Nerd Font icons it installs for you (or Unicode where there is none).
75
- - **A browser with real profiles** (optional `turno-browser`): an MCP server that drives your
76
- installed Chrome with one persistent profile per identity, so an agent works in the sessions
77
- you signed into by hand.
72
+ - **A browser with real profiles** (separate package `turno-browser`): an MCP server that
73
+ drives your installed Chrome with one persistent profile per identity, so an agent works in
74
+ the sessions you signed into by hand.
78
75
 
79
76
  ## Quick start
80
77
 
78
+ ```sh
79
+ turno init # finds your agents, profiles, folders and MCP servers, shows the diff,
80
+ # then starts the gateway and points every profile at it
81
+ claude-work # sign in once per profile (/login)
82
+ cd ~/code/acme && turno auto # Claude Code, with this folder's account
83
+ turno # where you stand: this folder, accounts, gateway, what to do next
84
+ ```
85
+
86
+ `turno init` asks before it adopts anything and writes everything as one change, so one
87
+ `turno undo <stamp>` reverts it. The gateway runs as a login service (launchd on macOS,
88
+ systemd --user on Linux); `turno init --no-start` leaves it for later (`turno mcp daemon start`,
89
+ then `turno mcp sync`). Step by step instead:
90
+
81
91
  ```sh
82
92
  turno profile add work --color violet # ~/.claude-work and the claude-work command
83
93
  turno profile add personal
84
94
  claude-work # sign in once per profile (/login)
85
95
  turno profile assign ~/code/acme work # this folder and everything under it
86
96
  turno config set default personal # folders without a rule
97
+ turno mcp import --move-secrets --write # mcp.toml from the servers you already have
98
+ turno mcp daemon start && turno mcp sync # the gateway, and every profile pointed at it
87
99
  cd ~/code/acme && turno auto # Claude Code, signed in as work
88
100
  ```
89
101
 
90
102
  Codex, Copilot and Cursor profiles are the same with `--agent codex|copilot|cursor`. Point your
91
103
  terminal or editor at `turno auto` (or the `turno-auto` launcher) and every folder opens with
92
- its account.
104
+ its account. Launchers go in `~/.local/bin`; when it is not on your `PATH`, `turno profile add`
105
+ prints the line to add, and `turno work` works meanwhile. `turno auto` never switches accounts
106
+ in silence: a missing profile or a broken `config.toml` stops it with the command that fixes it
107
+ ([docs/accounts.md](https://github.com/wimo-dev/turno/blob/main/docs/accounts.md)).
93
108
 
94
109
  ## Benchmark
95
110
 
@@ -130,52 +145,75 @@ usage limits or safeguards; see [Vendor terms](#vendor-terms).
130
145
 
131
146
  **Where are my credentials?** Where each agent keeps them, inside that profile's folder (or the
132
147
  Keychain where the agent uses it). turno never reads, copies or forwards login tokens. MCP
133
- secrets you move with `--move-secrets` go to the macOS Keychain.
148
+ secrets you move with `--move-secrets`, and the OAuth tokens of remote MCP servers, go to the
149
+ macOS Keychain or the Linux Secret Service. What turno stores where: [SECURITY.md](https://github.com/wimo-dev/turno/blob/main/SECURITY.md).
134
150
 
135
151
  **Does turno see my prompts or model traffic?** No. It launches the agent and gets out of the
136
- way. Only MCP tool calls go through `mcpd`, on `127.0.0.1`, with a bearer token, and requests
137
- with an `Origin` header are rejected so web pages cannot reach it.
138
-
139
- **Linux? Windows?** Linux works for everything except the Keychain and the LaunchAgent (both
140
- have open issues). Windows is not supported.
152
+ way. Only MCP tool calls go through `mcpd`, on `127.0.0.1`, with a bearer token per profile,
153
+ and requests with an `Origin` header are rejected so web pages cannot reach it.
154
+
155
+ **Linux? Windows?** Linux works too: secrets go to the Secret Service (`secret-tool`), mcpd runs
156
+ as a `systemd --user` unit, and links open with `xdg-open`. Windows is not supported.
157
+
158
+ **Can scripts and agents run turno?** Yes. turno asks only when a person is at a terminal: with
159
+ `--no-input` (or `TURNO_NO_INPUT=1`), when stdin is not a terminal, and inside a Claude Code,
160
+ Codex, Copilot CLI or Cursor agent session it never asks. A command that would ask exits with
161
+ code 2 and names the flag that answers it, for example `turno: init needs an answer; pass --yes
162
+ (or run it in a terminal)`. `TURNO_NO_INPUT=0` lets you answer in an editor terminal that sets
163
+ an agent's variable. A command that needs a profile and gets none (`turno profile assign`,
164
+ `turno run`, `turno session handoff`, `turno limit set`) shows a list to choose from on a
165
+ terminal (arrows or j/k, type to filter, Enter, Esc to cancel); `turno run` lists `auto` first,
166
+ named with the profile this folder resolves to (`auto (work)`). Elsewhere it exits with 2 and
167
+ lists the profiles: `pass a profile: personal, work`.
141
168
 
142
169
  **How do I undo it?** Every command that writes keeps a copy of each file it changes:
143
- `turno undo --list` shows them and `turno undo <stamp>` puts them back. To remove turno,
144
- `turno mcp daemon stop`, undo the `mcp sync`, delete the `claude-<p>`-style launchers in
145
- `~/.local/bin` and `npm uninstall --global turno-cli`. Profile folders stay until you delete them.
170
+ `turno undo --list` shows them and `turno undo <stamp>` puts them back (backups older than 30
171
+ days are pruned, keeping the newest 10). To remove turno, `turno uninstall --dry-run` lists what
172
+ turno set up (service, launchers, MCP entries, status line, config) and `turno uninstall`
173
+ removes it; then `npm uninstall --global turno-cli`. Profile folders, which hold your logins,
174
+ stay until you delete them. `turno uninstall --purge` also removes turno's state and caches
175
+ (backups, logs, usage, installed MCP servers), after which `turno undo` has nothing to restore.
146
176
 
147
177
  ## Reference
148
178
 
149
179
  `turno --help` groups the commands and `turno <command> --help` explains each. Commands that
150
180
  only read take `--json`; commands that write take `--dry-run`, keep a copy of each file they
151
- change, and print the `turno undo <stamp>` that puts them back.
181
+ change, and print the `turno undo <stamp>` that puts them back. `turno mcp import` only previews
182
+ (secrets masked) until `--write`.
152
183
 
153
184
  | Command | What it does |
154
185
  |---|---|
186
+ | `turno` | once set up, the status screen and the next step; before that, the help |
187
+ | `turno init [--dry-run] [--yes] [--start \| --no-start]` | set turno up in one step: agents, profiles, folder rules, mcp.toml, the gateway (one undo) |
188
+ | `turno demo [--keep] [-- <command>]` | try turno in a throwaway HOME (also `npx turno-cli demo`); without a terminal it shows what it set up and ends, `--keep` waits for Ctrl-C |
155
189
  | `turno <profile> [args]`, `turno run <profile\|auto> [args]` | the profile's agent with that account (args pass through) |
156
190
  | `turno auto [--agent codex\|copilot\|cursor]` | the profile assigned to the current folder |
157
191
  | `turno profile list\|add\|repair\|remove\|which\|assign\|unassign` | the profiles, and which folders use each |
158
- | `turno mcp list\|sync\|config\|import\|install\|refresh\|doctor\|daemon ...` | the MCP gateway, and entries for other agents |
159
- | `turno status` | one screen: this folder, profiles and usage, sessions, mcpd |
192
+ | `turno mcp list\|sync\|config\|import\|install\|refresh\|doctor` | the MCP gateway's servers, and entries for other agents |
193
+ | `turno mcp login\|logout <server>` | log mcpd in to an OAuth remote server, once per account |
194
+ | `turno mcp log\|top\|savings` | the gateway's tool call log, memory per server, and what it saves |
195
+ | `turno mcp daemon start\|stop\|restart\|status\|logs`, `turno mcp token rotate` | the gateway service, and its token |
196
+ | `turno status [--json]` | one screen: this folder, profiles and usage, sessions, mcpd, and the next step |
160
197
  | `turno limit show [--watch]\|set\|clear` | usage windows per account, and exhausted marks |
161
198
  | `turno session list\|handoff <p> [--fork]` | open sessions, and the command to continue this one under another profile |
162
- | `turno open [profile] <url>` | open a link; claude.ai links use that profile's Chrome profile |
163
- | `turno identity list\|add\|remove\|login\|prefer\|log` | service accounts for the bridge, browser identities |
164
- | `turno secret set\|has\|rm\|list` | MCP secrets in the macOS Keychain |
165
- | `turno browser bench` | how automation-fingerprint test pages see each browser engine |
199
+ | `turno open [profile] <url>` | open an http(s) or mailto link; claude.ai links use that profile's Chrome profile |
200
+ | `turno identity list\|add\|remove\|login\|prefer\|log [--verify]` | service accounts for the bridge, browser identities, the audit log |
201
+ | `turno secret set\|has\|rm\|list` | MCP secrets in the macOS Keychain or the Linux Secret Service |
166
202
  | `turno ui status\|install` | the status line, its font and icons in every terminal |
167
- | `turno doctor [--fix]` | check everything and repair what is safe to repair |
203
+ | `turno doctor [--fix]`, `turno doctor --security [--fix]` | check everything and repair what is safe to repair; `--security` checks file modes, the port owner, literal secrets, unpinned servers, token age and the audit log |
168
204
  | `turno config path\|get\|set\|unset\|edit\|check` | config.toml without losing its comments |
169
- | `turno undo [--list] [<stamp>\|last]` | put back the files a command changed |
205
+ | `turno undo [--list] [<stamp>\|last]`, `turno undo --prune` | put back the files a command changed; prune old backups |
170
206
  | `turno upgrade [--check]`, `turno version` | update turno the way it was installed |
207
+ | `turno uninstall [--dry-run] [--yes] [--keep-config] [--purge]` | remove what turno set up (profile folders stay); `--purge` also removes its state and caches |
171
208
  | `turno completion zsh\|bash\|fish` | shell completion, including profiles and config keys |
209
+ | `turno browser bench` | developer diagnostic: browser engine compatibility (needs `turno-browser`) |
172
210
 
173
211
  ### Config
174
212
 
175
213
  `~/.config/turno/config.toml`:
176
214
 
177
215
  ```toml
178
- system = "personal" # account the plain `claude` command uses
216
+ system = "personal" # account the plain `claude` command uses ("" for none)
179
217
  default = "personal" # profile for folders without a rule
180
218
  # fallback = "work" # optional, off unless set; read "Vendor terms" first
181
219
 
@@ -189,8 +227,22 @@ agent = "codex"
189
227
  [[projects]]
190
228
  path = "~/code/acme"
191
229
  profile = "work"
230
+
231
+ [[projects]]
232
+ path = "~/code/oss"
233
+ mcp_deny = ["mail"] # sessions here see every MCP server but mail
234
+
235
+ [mcpd]
236
+ port = 47821
237
+ # idle_under_pressure = "5m" # idle limit while memory is low; false turns it off
238
+ # max_request_body = "32MiB" # between 1MiB and 1GiB
239
+ # call_log = true # logs/calls.jsonl, no arguments or results
192
240
  ```
193
241
 
242
+ A rule may carry a `profile`, a server set (`mcp = [...]` keeps only those servers, `mcp_deny`
243
+ removes some), or both. With `system = ""` there is no default account, so `turno auto` needs a
244
+ rule ([docs/accounts.md](https://github.com/wimo-dev/turno/blob/main/docs/accounts.md)). `turno config --help` lists every key.
245
+
194
246
  ### MCP gateway
195
247
 
196
248
  `~/.config/turno/mcp.toml`:
@@ -198,7 +250,7 @@ profile = "work"
198
250
  ```toml
199
251
  [server.calendar]
200
252
  command = "cal-mcp"
201
- package = "@calcom/cal-mcp@1.4.0" # `turno mcp install` pins it instead of npx per start
253
+ package = "@calcom/cal-mcp@1.4.0" # installed by `turno mcp install` (see below)
202
254
  env = { CAL_API_KEY = "keychain:turno/calendar/api-key" }
203
255
  scope = "shared" # one process for every session
204
256
 
@@ -212,23 +264,30 @@ command = "issues-mcp"
212
264
  [server.issues.variant.work] # the work profile reaches a different account
213
265
  env = { ISSUES_TOKEN = "keychain:turno/issues/work" }
214
266
 
267
+ [server.linear]
268
+ url = "https://mcp.linear.app/mcp"
269
+ auth = "oauth" # mcpd logs in once per account: turno mcp login linear
270
+
215
271
  [server.docs]
216
- url = "https://docs.example.com/mcp" # remote, written straight into each profile
272
+ url = "https://docs.example.com/mcp" # remote, no secrets: written straight into each profile
217
273
  ```
218
274
 
219
275
  Each variant per profile runs separately, so two profiles can reach two accounts of the same
220
- service. Details: [docs/mcp.md](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md).
276
+ service. A remote server with `auth = "oauth"` or secret headers goes through mcpd, so no agent
277
+ logs in to it on its own. `turno mcp install` installs each `package` at an exact version,
278
+ without install scripts (`--allow-scripts` to run them) and with a lockfile per server; until
279
+ then npx runs it, with a warning in the server's log. Details: [docs/mcp.md](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md).
221
280
 
222
281
  ### Browser with real profiles
223
282
 
224
283
  ```sh
225
- npm install --global turno-browser # optional
284
+ npm install --global turno-browser # separate package, not installed with turno
226
285
  turno identity add browser:school # an identity and its mcp.toml entry
227
286
  turno identity login browser:school # sign in by hand once; cookies persist
228
287
  ```
229
288
 
230
289
  It drives the installed Google Chrome, headed, with a persistent profile per identity and no
231
- injected scripts ([ADR 0005](https://github.com/wimo-dev/turno/blob/main/docs/decisions/0005-stealth-browser-defaults.md)).
290
+ injected scripts. Why it is a separate package: [ADR 0019](https://github.com/wimo-dev/turno/blob/main/docs/decisions/0019-lean-install-browser-framing-shrinkwrap.md).
232
291
 
233
292
  **Acceptable use.** Use it with your own accounts, on sites whose terms allow automated access
234
293
  by you, and at a human pace. Do not use it to get around access controls, paywalls, CAPTCHAs or
@@ -238,8 +297,10 @@ rate limits, to scrape at scale, or to access accounts that are not yours.
238
297
 
239
298
  A builtin MCP server (`builtin = "accounts"` in `mcp.toml`) lets a session in one profile
240
299
  delegate a task to a service account (a Linear workspace, a mail connector) that only another
241
- profile is signed into. Write tasks need your confirmation, and every call goes to an audit log
242
- (`turno identity log`).
300
+ profile is signed into. Reads run with only the account's read tools; writes, and by default
301
+ every call to a mail or messaging account, need your confirmation. Every call and its decision
302
+ go to a hash-chained audit log (`turno identity log`, `--verify` checks the chain). Details:
303
+ [docs/accounts.md](https://github.com/wimo-dev/turno/blob/main/docs/accounts.md).
243
304
 
244
305
  ### Status line
245
306
 
@@ -257,8 +318,9 @@ Details: [docs/ui.md](https://github.com/wimo-dev/turno/blob/main/docs/ui.md).
257
318
 
258
319
  ### Claude Code plugin
259
320
 
260
- `plugins/turno` adds session handoff and fork skills and a hook that records when a profile
261
- reaches its usage limit, so `turno status` can show it:
321
+ `plugins/turno` adds session handoff and fork skills, a `copy-artifact` skill that copies a
322
+ claude.ai artifact (with its files and assets) from one profile's account to another, and a hook
323
+ that records when a profile reaches its usage limit, so `turno status` can show it:
262
324
 
263
325
  ```
264
326
  /plugin marketplace add wimo-dev/turno
@@ -272,7 +334,7 @@ reaches its usage limit, so `turno status` can show it:
272
334
  | `~/.config/turno/config.toml` | profiles and folder rules |
273
335
  | `~/.config/turno/mcp.toml` | MCP servers behind the gateway |
274
336
  | `~/.config/turno/accounts.toml` | service accounts for the bridge |
275
- | `~/.local/state/turno/` | usage, run records, logs, backups, the mcpd token |
337
+ | `~/.local/state/turno/` | usage, run records, logs (with the tool call log `logs/calls.jsonl`), backups, the gateway tokens |
276
338
  | `~/.local/share/turno/` | installed servers, tool cache, browser identities |
277
339
 
278
340
  All three honor `XDG_CONFIG_HOME`, `XDG_STATE_HOME` and `XDG_DATA_HOME`.
@@ -304,14 +366,18 @@ traffic: every agent logs in by itself, in its own directory. Before you use sev
304
366
 
305
367
  turno is provided "as is", without warranty of any kind (Apache License 2.0, sections 7 and 8).
306
368
  It edits agent config files and launches programs as your user; every write keeps a backup
307
- that `turno undo` restores.
369
+ that `turno undo` restores, and `turno uninstall` removes what it set up.
308
370
 
309
371
  ### Update check
310
372
 
311
373
  Interactive commands ask the npm registry for a newer version at most once a day, sending only
312
374
  the package name. Turn it off with `update_check = false` in config.toml, `DO_NOT_TRACK=1`,
313
375
  `NO_UPDATE_NOTIFIER=1` or `TURNO_NO_UPDATE_CHECK=1`; it is also off in CI and outside a
314
- terminal. turno sends no other data anywhere.
376
+ terminal. Apart from that, turno only goes online when you ask it to: `turno ui install`
377
+ downloads the status line font, `turno mcp install` and `turno upgrade` fetch packages from npm,
378
+ `turno mcp import --write` and `turno init` (once you confirm) ask npm for the command name of
379
+ servers you ran with npx, and `turno mcp login` talks to that server's authorization server.
380
+ Previews (`--dry-run`, `turno mcp import` without `--write`) stay offline. There is no telemetry.
315
381
 
316
382
  ## Contributing
317
383
 
@@ -323,7 +389,8 @@ category). Security issues: [SECURITY.md](https://github.com/wimo-dev/turno/blob
323
389
 
324
390
  ```sh
325
391
  pnpm install && pnpm build
326
- pnpm check # typecheck, tests (sandboxed HOME), repository text rules, licenses
392
+ pnpm check # typecheck, lint (Biome, knip), tests (sandboxed HOME), text rules, licenses
393
+ pnpm test:e2e # also the end-to-end test that needs the network (Cursor)
327
394
  ```
328
395
 
329
396
  Design: [docs/design](https://github.com/wimo-dev/turno/blob/main/docs/design/2026-11-12-claudio-ecosystem-design.md). Decisions:
@@ -1,8 +1,77 @@
1
- import { appendFileSync, chmodSync, mkdirSync, readFileSync } from "node:fs";
1
+ import { createHash } from "node:crypto";
2
+ import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, rmdirSync, statSync, writeSync } from "node:fs";
2
3
  import { dirname } from "node:path";
3
- import { paths } from "../core/paths.js";
4
- export const TASK_LIMIT = 500;
5
- /** Append one entry (file mode 600). Never throws: auditing must not break a delegation. */
4
+ import { PRIVATE_FILE_MODE, ensurePrivateDir, paths } from "../core/paths.js";
5
+ const TASK_LIMIT = 500;
6
+ /** `prev` of the first chained line of an empty log. */
7
+ export const GENESIS = "0".repeat(64);
8
+ function lineHash(line) {
9
+ return createHash("sha256").update(line, "utf8").digest("hex");
10
+ }
11
+ /** The last non-empty line of an open file, read from its tail. */
12
+ function lastLine(fd) {
13
+ const size = fstatSync(fd).size;
14
+ if (size === 0)
15
+ return undefined;
16
+ let chunk = 4096;
17
+ for (;;) {
18
+ const len = Math.min(chunk, size);
19
+ const buf = Buffer.alloc(len);
20
+ readSync(fd, buf, 0, len, size - len);
21
+ const text = buf.toString("utf8").replace(/\n+$/, "");
22
+ const nl = text.lastIndexOf("\n");
23
+ if (nl >= 0 || len === size)
24
+ return text.slice(nl + 1) || undefined;
25
+ chunk *= 4;
26
+ }
27
+ }
28
+ /** Sleep without a timer: appends are synchronous and rare. */
29
+ function pause(ms) {
30
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
31
+ }
32
+ /**
33
+ * Hold a lock folder next to the log while `fn` runs, so two writers do not chain to the same
34
+ * line. A lock older than 10 s is stale (a crashed writer) and taken over.
35
+ */
36
+ function withLock(file, fn) {
37
+ const lock = `${file}.lock`;
38
+ const deadline = Date.now() + 2000;
39
+ for (;;) {
40
+ try {
41
+ mkdirSync(lock, { mode: 0o700 });
42
+ break;
43
+ }
44
+ catch (err) {
45
+ if (err.code !== "EEXIST")
46
+ throw err;
47
+ try {
48
+ if (Date.now() - statSync(lock).mtimeMs > 10_000)
49
+ rmdirSync(lock);
50
+ }
51
+ catch {
52
+ /* someone else removed it */
53
+ }
54
+ if (Date.now() > deadline)
55
+ break; // write anyway: verifyAudit will show the fork
56
+ pause(10);
57
+ }
58
+ }
59
+ try {
60
+ return fn();
61
+ }
62
+ finally {
63
+ try {
64
+ rmdirSync(lock);
65
+ }
66
+ catch {
67
+ /* already gone */
68
+ }
69
+ }
70
+ }
71
+ /**
72
+ * Append one entry: the file is opened append-only with mode 600, and the line carries the hash
73
+ * of the line before it. Never throws: auditing must not break a delegation.
74
+ */
6
75
  export function appendAudit(entry, env = process.env) {
7
76
  const full = {
8
77
  ts: entry.ts ?? new Date().toISOString(),
@@ -15,12 +84,25 @@ export function appendAudit(entry, env = process.env) {
15
84
  detail: entry.detail,
16
85
  durationMs: entry.durationMs,
17
86
  costUsd: entry.costUsd,
87
+ ...(entry.decision ? { decision: entry.decision } : {}),
18
88
  };
19
89
  const file = paths(env).auditLog;
20
90
  try {
21
- mkdirSync(dirname(file), { recursive: true });
22
- appendFileSync(file, `${JSON.stringify(full)}\n`, { mode: 0o600 });
23
- chmodSync(file, 0o600);
91
+ ensurePrivateDir(dirname(file), env);
92
+ withLock(file, () => {
93
+ // "a+": every write lands at the end (O_APPEND) and the tail can still be read.
94
+ const fd = openSync(file, "a+", PRIVATE_FILE_MODE);
95
+ try {
96
+ if ((fstatSync(fd).mode & 0o777) !== PRIVATE_FILE_MODE)
97
+ chmodSync(file, PRIVATE_FILE_MODE);
98
+ const last = lastLine(fd);
99
+ full.prev = last === undefined ? GENESIS : lineHash(last);
100
+ writeSync(fd, `${JSON.stringify(full)}\n`);
101
+ }
102
+ finally {
103
+ closeSync(fd);
104
+ }
105
+ });
24
106
  }
25
107
  catch {
26
108
  /* best effort */
@@ -51,4 +133,52 @@ export function readAudit(limit = 20, env = process.env) {
51
133
  }
52
134
  return limit > 0 ? out.slice(-limit) : out;
53
135
  }
136
+ /**
137
+ * Check the hash chain of the audit log. It catches an edited, inserted, reordered or deleted
138
+ * line, and lines removed from the start. It cannot catch lines cut from the end (nothing
139
+ * commits to the last line), and anyone who can write the file can rebuild the chain: it shows
140
+ * accidents and naive tampering, it is not a signature.
141
+ */
142
+ export function verifyAudit(env = process.env) {
143
+ let text = "";
144
+ try {
145
+ text = readFileSync(paths(env).auditLog, "utf8");
146
+ }
147
+ catch (err) {
148
+ if (err.code === "ENOENT")
149
+ return { ok: true, lines: 0, legacy: 0 };
150
+ throw err;
151
+ }
152
+ const raw = text.split("\n");
153
+ let lines = 0;
154
+ let legacy = 0;
155
+ let chained = false;
156
+ let prevLine;
157
+ for (const [i, line] of raw.entries()) {
158
+ if (!line.trim())
159
+ continue;
160
+ lines++;
161
+ const fail = (reason) => ({ ok: false, lines, legacy, line: i + 1, reason });
162
+ let entry;
163
+ try {
164
+ entry = JSON.parse(line);
165
+ }
166
+ catch {
167
+ return fail("not valid JSON");
168
+ }
169
+ if (entry.prev === undefined) {
170
+ if (chained)
171
+ return fail("line without a hash after the chain started (added by hand?)");
172
+ legacy++;
173
+ }
174
+ else {
175
+ const expected = prevLine === undefined ? GENESIS : lineHash(prevLine);
176
+ if (entry.prev !== expected)
177
+ return fail(prevLine === undefined ? "first line does not start the chain (lines removed from the start?)" : "hash does not match the previous line (edited, removed or reordered)");
178
+ chained = true;
179
+ }
180
+ prevLine = line;
181
+ }
182
+ return { ok: true, lines, legacy };
183
+ }
54
184
  //# sourceMappingURL=audit.js.map