turno-cli 0.2.0 → 0.4.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 (116) hide show
  1. package/CHANGELOG.md +266 -0
  2. package/README.md +134 -42
  3. package/dist/accounts/audit.js +27 -15
  4. package/dist/accounts/builtin.js +35 -7
  5. package/dist/accounts/delegate.js +30 -7
  6. package/dist/accounts/policy.js +4 -2
  7. package/dist/accounts/registry.js +3 -1
  8. package/dist/agents/adapter.js +22 -0
  9. package/dist/agents/claude.js +54 -3
  10. package/dist/agents/codex.js +94 -6
  11. package/dist/agents/copilot.js +19 -2
  12. package/dist/agents/cursor.js +19 -2
  13. package/dist/agents/index.js +1 -1
  14. package/dist/agents/snippets.js +37 -10
  15. package/dist/cli/args.js +32 -15
  16. package/dist/cli/commands/accounts.js +29 -7
  17. package/dist/cli/commands/auto.js +50 -12
  18. package/dist/cli/commands/browser-do-session.js +170 -0
  19. package/dist/cli/commands/browser-do.js +740 -0
  20. package/dist/cli/commands/browser-flows.js +300 -0
  21. package/dist/cli/commands/browser-identity.js +952 -0
  22. package/dist/cli/commands/browser-live.js +118 -0
  23. package/dist/cli/commands/browser-session.js +102 -0
  24. package/dist/cli/commands/browser-vault.js +193 -0
  25. package/dist/cli/commands/browser.js +303 -62
  26. package/dist/cli/commands/complete.js +13 -3
  27. package/dist/cli/commands/completion.js +4 -0
  28. package/dist/cli/commands/config.js +90 -13
  29. package/dist/cli/commands/demo.js +36 -7
  30. package/dist/cli/commands/doctor.js +170 -36
  31. package/dist/cli/commands/identity.js +101 -12
  32. package/dist/cli/commands/init.js +42 -10
  33. package/dist/cli/commands/limit.js +65 -9
  34. package/dist/cli/commands/mcp-call.js +240 -0
  35. package/dist/cli/commands/mcp-oauth.js +33 -6
  36. package/dist/cli/commands/mcp-observe.js +128 -23
  37. package/dist/cli/commands/mcp-share.js +201 -0
  38. package/dist/cli/commands/mcp.js +203 -42
  39. package/dist/cli/commands/mcpd.js +76 -12
  40. package/dist/cli/commands/open.js +26 -3
  41. package/dist/cli/commands/profile.js +212 -30
  42. package/dist/cli/commands/resolve.js +8 -1
  43. package/dist/cli/commands/run.js +24 -4
  44. package/dist/cli/commands/secret.js +23 -38
  45. package/dist/cli/commands/session.js +16 -5
  46. package/dist/cli/commands/sessions.js +7 -1
  47. package/dist/cli/commands/setup.js +83 -11
  48. package/dist/cli/commands/status.js +67 -15
  49. package/dist/cli/commands/statusline.js +7 -2
  50. package/dist/cli/commands/ui.js +17 -5
  51. package/dist/cli/commands/undo.js +39 -7
  52. package/dist/cli/commands/uninstall.js +24 -5
  53. package/dist/cli/commands/upgrade.js +113 -76
  54. package/dist/cli/commands/usage.js +11 -10
  55. package/dist/cli/commands/version.js +20 -8
  56. package/dist/cli/commands/which.js +5 -3
  57. package/dist/cli/diagnostics.js +184 -0
  58. package/dist/cli/exit.js +65 -0
  59. package/dist/cli/group.js +20 -8
  60. package/dist/cli/help.js +6 -1
  61. package/dist/cli/hints.js +30 -0
  62. package/dist/cli/io.js +24 -8
  63. package/dist/cli/launch.js +31 -2
  64. package/dist/cli/launchers.js +25 -10
  65. package/dist/cli/main.js +52 -18
  66. package/dist/cli/optional.js +144 -0
  67. package/dist/cli/output.js +123 -0
  68. package/dist/cli/picker.js +17 -5
  69. package/dist/cli/registry.js +20 -2
  70. package/dist/cli/safe.js +87 -0
  71. package/dist/cli/secret-input.js +63 -0
  72. package/dist/cli/security.js +31 -9
  73. package/dist/cli/style.js +35 -5
  74. package/dist/cli/topics.js +155 -0
  75. package/dist/core/config.js +39 -3
  76. package/dist/core/fsutil.js +2 -10
  77. package/dist/core/journal.js +19 -11
  78. package/dist/core/manifest.js +28 -1
  79. package/dist/core/paths.js +6 -112
  80. package/dist/core/profiles.js +28 -8
  81. package/dist/core/resolve.js +13 -3
  82. package/dist/core/secrets.js +4 -154
  83. package/dist/core/state-file.js +107 -0
  84. package/dist/core/update.js +14 -11
  85. package/dist/core/version.js +57 -10
  86. package/dist/demo/server.js +10 -2
  87. package/dist/mcpd/cache.js +6 -7
  88. package/dist/mcpd/calllog.js +10 -9
  89. package/dist/mcpd/client-names.js +8 -13
  90. package/dist/mcpd/connectors.js +42 -3
  91. package/dist/mcpd/daemon.js +29 -8
  92. package/dist/mcpd/folder-sets.js +5 -2
  93. package/dist/mcpd/gateway.js +57 -29
  94. package/dist/mcpd/health.js +70 -26
  95. package/dist/mcpd/importer.js +106 -9
  96. package/dist/mcpd/instances.js +70 -32
  97. package/dist/mcpd/jsonrpc.js +3 -1
  98. package/dist/mcpd/middleware.js +156 -0
  99. package/dist/mcpd/modern.js +57 -19
  100. package/dist/mcpd/oauth.js +71 -17
  101. package/dist/mcpd/peerpid.js +63 -17
  102. package/dist/mcpd/pressure.js +4 -1
  103. package/dist/mcpd/rss.js +34 -19
  104. package/dist/mcpd/service.js +28 -4
  105. package/dist/mcpd/share.js +217 -0
  106. package/dist/mcpd/state.js +16 -16
  107. package/dist/mcpd/sync.js +22 -12
  108. package/dist/mcpd/systemd.js +4 -1
  109. package/dist/mcpd/tokens.js +4 -8
  110. package/dist/mcpd/upstream.js +12 -5
  111. package/dist/statusline/cost.js +17 -4
  112. package/dist/statusline/input.js +15 -3
  113. package/dist/ui/fonts.js +1 -1
  114. package/dist/ui/settings.js +6 -1
  115. package/npm-shrinkwrap.json +12 -3
  116. package/package.json +7 -6
package/CHANGELOG.md CHANGED
@@ -1,5 +1,271 @@
1
1
  # turno-cli
2
2
 
3
+ ## 0.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 50facc9: Record and replay. `browser_record` saves an agent's actions on an identity as a named flow, each
8
+ element kept four ways (Playwright's locator, role and name, text, CSS path) and typed text as
9
+ parameters; passwords, one-time codes and values marked sensitive are never saved, and a vault
10
+ sign-in is kept as `browser_login` with the site name. `browser_replay` runs a flow with
11
+ parameters (`keychain:<item>` reads one from the secret store) and, when a step no longer fits,
12
+ stops with a report the agent can continue from; `browser_flows` lists them. Opt-in per identity
13
+ (`record` in identity.json, `turno browser record <id>`): every session as a flow, Playwright
14
+ traces and a screenshot per action under a size cap, with the trace stopped around sign-ins.
15
+ New commands `turno browser flows|replay|record|traces`; `traces --open` uses the trace viewer
16
+ bundled with patchright-core.
17
+ With `"sharing": "tabs"` a recording holds only the session that started it and replay runs in
18
+ that session's tabs; traces and screenshots are refused in attach mode and in read mode.
19
+ - e94a153: Natural language actions and captcha solving for browser identities, both not recommended and off by default.
20
+
21
+ - `turno identity set browser:<id> --act` lists `browser_act` (an instruction carried out one stock browser action at a time, every step shown), `browser_extract` (data off the page as JSON) and `browser_observe` (proposed calls, not run). The model is your client's, through MCP sampling, or a chat completions API you name with `--act-provider chat-completions --act-endpoint <url> --act-model <name> --act-key keychain:<item>`. The model sees the instruction and a snapshot of the current tab with vault values and password, one-time code and card fields hidden; it can only click, type, select, press keys, hover, drag, wait and go back on that tab; steps, tokens and time are capped per call (`--act-max-steps`, `--act-max-tokens`, `--act-timeout`). A recorded flow keeps the stock steps it chose, never the instruction or the page.
22
+ - `--captcha-provider task-api --captcha-endpoint <url> --captcha-key keychain:<item>` lists `browser_solve_captcha`, which sends a reCAPTCHA v2, hCaptcha or Turnstile widget and the page address to that solver service and puts the token into the page. The service sees the page, and solving a site's captchas by machine may break its terms: it is meant for your own accounts. Every attempt is a line in the identity's reputation log, and `turno browser reputation` shows a `solved` column once a solver answered. Read mode refuses it.
23
+ - Keys are only `keychain:` references read from the secret store at use time, refused as literal values without being echoed, and hidden from every result.
24
+ - identity.json format 8 (`act`, `captcha`); turno-browser API 1.7, which turno-cli now requires.
25
+ - dcc2b97: Two opt-in engines for browser identities and servers, both off by default.
26
+
27
+ Read mode runs an identity (or one server) on Lightpanda instead of Chrome, for reading pages
28
+ with a fraction of the memory: `turno browser set <id> --engine lightpanda`, or
29
+ `turno-browser-mcp --engine lightpanda`. turno never downloads Lightpanda; it runs the
30
+ `lightpanda` on your PATH (or at `TURNO_LIGHTPANDA_PATH`), on a private Unix socket with
31
+ Lightpanda's telemetry off. The tools that work there run; the others (screenshots, dialogs,
32
+ drag and drop, uploads, `browser_login`) are refused with the reason before they reach the
33
+ browser. An identity in read mode keeps its own cookie jar, apart from its Chrome profile.
34
+
35
+ Attach mode connects to the Chrome you already have open, so the agent works in your signed-in
36
+ browser: `turno browser set <id> --attach auto` (after you turn on remote debugging at
37
+ chrome://inspect/#remote-debugging, Chrome 144 or newer), a Chrome user data folder, or a
38
+ loopback endpoint; `turno-browser-mcp --attach <target>` for one server. Chrome asks you to allow
39
+ each connection. turno works in a tab of its own, closes only the tabs it opened (on
40
+ `browser_close`, at the end of the session and at the idle limit) and never closes Chrome; the
41
+ tab governor leaves your tabs alone, and `browser_run_code_unsafe` is refused.
42
+
43
+ `turno browser doctor` gains an Engines section (Lightpanda found or how to install it, a
44
+ Lightpanda left running, which `--fix` stops) and checks each identity's attach target without
45
+ connecting. identity.json is now format 6 (`engine`, `attach`), and the turno-browser API is 1.5.
46
+
47
+ Read mode works with `"sharing": "tabs"`. Two pairs are refused with the reason, in identity.json
48
+ and from server flags: attach mode with `"sharing": "tabs"` (turno keeps one agent's tabs apart
49
+ from yours in your Chrome, not several sessions apart), and read mode with `humanize` (Lightpanda
50
+ lays out no page, so there is no pointer path to play). Attach mode works with `humanize`.
51
+ - 4814fb8: Human-like input for browser identities, off by default. `turno identity set browser:<id> --humanize light|full|adaptive` (or `turno-browser-mcp --humanize <level>`, which wins) makes the stock click, hover, type, fill form, select, drag, press key and coordinate tools, and `browser_batch`, move the pointer along a curve from where it last was to a point inside the target, hold the button for tens of milliseconds and type short text key by key with per-key delays. `full` adds a move time that follows distance and target size, overshoot and correction, a reading pause on a new page, longer gaps between words and wheel scrolling; `adaptive` is `light`, and `full` on a site where the identity met a challenge page. Tool names, arguments and results do not change. The setting is the `humanize` key of identity.json (format 4, with an optional `seed`), and turno-cli needs turno-browser API 1.3 for it.
52
+ - bf1cafb: `turno browser do <id> <action>` drives a browser identity from the shell, for coding agents that
53
+ prefer commands to MCP tools: `open`, `back`, `snapshot`, `read`, `find`, `click`, `type`,
54
+ `press`, `select`, `hover`, `wait`, `screenshot`, `tabs`, `login` (a vault sign-in), `call` (any
55
+ tool of the server), `close`, `session` and `end`. Each action is one tool call through mcpd to the
56
+ identity's turno-browser-mcp, so the tab locks or the one-session lease, attach mode, read mode's
57
+ refusals, humanize, recordings and the vault apply as they do to an agent. The commands one agent
58
+ or one terminal shell runs are one session and keep their tab: turno keeps the mcpd session open
59
+ between them and ties it to the agent (or the shell), and `end` closes it; `--session <name>` or
60
+ `TURNO_BROWSER_SESSION` keeps several apart. Output is `url:` and `title:` lines and what the
61
+ action returned, errors on stderr with exit 1, or one object with `--json`. `turno browser <id>
62
+ <action>` is the short form when the id is not a subcommand. The Claude Code plugin adds a short
63
+ `browser-identity` skill that teaches the loop and reads the installed help first.
64
+ - 6698608: Live view and take-over for browser identities, off by default. `turno browser set <id> --live true` (or `turno-browser-mcp --live`) serves a view of the agent's tab on 127.0.0.1 with a per-server token; `turno browser live <id>` opens it through a link that works once and is never printed. `turno browser pause <id>` (or Pause in the view) holds the agent's next call, up to `live.wait` (2 minutes by default), while you act in the window or through the view; `turno browser resume <id>` lets it go, and each held call is told what changed (URL, title, tabs, your input) and a call that would act on stale refs is not run: it returns an error with a fresh snapshot. The natural language and captcha tools are held too, and a `browser_act` run stops at its next step. A page that holds a vault value or a password is never shown, including a sign-in typed key by key with humanize. Read mode and attach mode refuse the view and keep pause and resume. turno-browser API 1.9, identity.json format 10.
65
+ - c716051: Opt-in network and user agent settings, and a Camoufox engine, all off by default and not
66
+ recommended for your own accounts. identity.json format 11 adds `userAgent` and `proxy`, and the
67
+ `engine` key takes `"camoufox"` (also format 11); API_VERSION is 1.10 and turno-cli needs it.
68
+ `"userAgent": "coherent"` takes no typed value: a headless Chrome gets the user agent a headed one
69
+ of the same version sends, with its real client hints metadata, and a launch check refuses any
70
+ contradiction between the user agent, client hints, platform, headers, languages and time zone.
71
+ `proxy` sends the identity's traffic (sign-ins included) through an http, https or SOCKS proxy,
72
+ with its password only from the secret store, hidden from every tool result, and WebRTC limited
73
+ to the proxy. `--engine camoufox` runs an identity on an installed Camoufox through stock
74
+ playwright-core, with its own Firefox profile; turno never downloads it, and every stock tool but
75
+ `browser_run_code_unsafe` runs, as do natural language actions, `browser_login` and
76
+ `turno browser do`. Captcha solving is refused with it, and the live view shows no picture there
77
+ (pause and resume work). The act model's prompt and the live view's tab list hide the proxy
78
+ credentials. New flags on `turno identity set` (`--user-agent`,
79
+ `--proxy-server`, `--proxy-username`, `--proxy-password`, `--no-proxy`), doctor checks for
80
+ Camoufox and the proxy credentials, and fingerprint bench checks that compare headers and a
81
+ worker with the page.
82
+ - 4b9556f: Several agent sessions can now share one browser identity, each in its own tabs. Turn it on per identity with `"sharing": "tabs"` in identity.json (`turno identity set browser:<id> --sharing tabs`, or the server's `--sharing tabs`) and serve the identity with `exclusive = false` in mcp.toml; the default stays one session at a time. Each session gets its own current tab and holds the tabs it works on: another session's call on one of them waits up to 10 seconds and then fails with a message that names the holder. A session lets go of its tabs when it ends (mcpd now tells servers that declare the `io.turno/sessions` capability), when a tab closes, or after 5 minutes without a call. `browser_close` closes only the calling session's tabs, tab lists mark the tabs other sessions hold, and the tab governor's cap counts each session's tabs apart. `turno identity add browser:<id> --sharing tabs` prints the matching mcp.toml block. turno-browser's API version is now 1.4.
83
+ - 3bd7bc2: Follow-ups for browser identities.
84
+
85
+ A tool call no longer starts while the tab governor is still closing a popup or a parked tab, so
86
+ the call cannot fail with "Target page, context or browser has been closed". A Chrome that does
87
+ not stop after SIGKILL gets 5 seconds instead of 2 before turno calls it a survivor.
88
+
89
+ A server in read mode stops a Lightpanda that a killed server left running on the same cookie jar
90
+ when it starts, and removes its socket folder.
91
+
92
+ `turno browser doctor` warns when an identity that serves one session at a time
93
+ (`"sharing": "session"`) is served by an mcp.toml server with `exclusive = false`, and says how to
94
+ switch it to `"sharing": "tabs"`.
95
+
96
+ The tab lock wait (10 seconds) and the idle release (5 minutes) of `"sharing": "tabs"` can be set
97
+ per identity: `"tabLocks": { "wait": "30s", "release": "10m" }` in identity.json, or
98
+ `turno browser set <id> --tab-lock-wait 30s --tab-lock-release 10m`. identity.json is now format
99
+ 9 and the turno-browser API is 1.8.
100
+
101
+ The `light` humanize level moves the pointer on a visible arc (some 4 to 8% longer than the
102
+ straight line) instead of an almost straight path. With humanize on, `browser_login` clicks into
103
+ each field and types the value key by key; the keys go to Chrome only, never to a result, a
104
+ recording or a log.
105
+
106
+ When another element covers the target of a click, hover, type, select or drag before the call,
107
+ and still covers it 300 ms later, the error names that element at once instead of after the 5
108
+ second action timeout.
109
+
110
+ Chrome keeps its third-party storage partitioning on, as a person's Chrome does: Playwright turns
111
+ it off, and turno now passes Playwright's list of disabled features without it.
112
+
113
+ ### Patch Changes
114
+
115
+ - 31a9a36: `turno doctor`, `turno status`, `turno mcp daemon status` and `turno doctor --security` no longer
116
+ wait for lsof to tell who holds mcpd's port. A free port is told by a refused connection, and a
117
+ running mcpd's port is checked against the pid it reports, so lsof's scan of every process (which
118
+ takes seconds on a busy Mac) runs only when another process holds the port. When lsof cannot say
119
+ which process that is, doctor still reports the port as in use.
120
+
121
+ ## 0.3.0
122
+
123
+ ### Minor Changes
124
+
125
+ - cc6b5b2: Browser identity module:
126
+
127
+ - `identity.json` next to each identity's profile keeps its time zone, languages, locale and
128
+ region fixed; Chrome gets them at every start (`--accept-lang`, `--lang`, and the time zone
129
+ when it differs from the machine's). `turno identity add browser:<id>` pins a new identity to
130
+ the current time zone and takes `--timezone`, `--locale`, `--languages`, `--region` and a
131
+ health check; `turno identity show` and `turno identity set` read and change it
132
+ (`turno browser show/set <id>` too). Without the file nothing changes.
133
+ - A runtime lock (`{ nodePid, chromePid, pgid, startedAt }`) while an identity's Chrome runs: a
134
+ second session gets a message naming the process and how to stop it instead of "Browser is
135
+ already in use".
136
+ - An optional session health check (a URL and a text or selector) marks a signed-out identity
137
+ NEEDS_AUTH; tool calls then fail with a message that asks for `turno browser login <id>`.
138
+ - Each captcha, "verify it's you" or block page an identity meets is logged per site (host name
139
+ only); `turno browser reputation [<id>] [--json]` shows counts and trend.
140
+ - `turno browser doctor [--fix] [--no-launch] [--json]`: Chrome and its version, a smoke launch,
141
+ the desktop session, and per identity its settings, lock, sign-in and recent challenges, with
142
+ a fix for each problem.
143
+ - mcpd: `stop_grace` per server in `mcp.toml`, the wait between closing stdin and SIGTERM;
144
+ 5 seconds by default for turno-browser-mcp, the SDK's 2 seconds for every other server.
145
+ - 59309b5: `turno browser export <id> --out <file>` and `turno browser import <file> [--as <id>]` move an
146
+ identity's cookies, localStorage and IndexedDB as one file encrypted with a passphrase (scrypt
147
+ and AES-256-GCM), refused after its expiry and never holding vault credentials.
148
+ `"keychain": "system"` in identity.json makes Chrome encrypt an identity's cookies with the OS
149
+ keychain instead of Playwright's fixed mock key; the default is unchanged.
150
+ turno-browser's API is now 1.2, which this turno requires.
151
+ - 50dd77c: Credential vault for browser identities: `turno browser vault add|list|remove|submit`
152
+ stores a username, a password and an optional TOTP secret per site in the OS secret store, and
153
+ the new `browser_login` tool fills them into the site's sign-in page without the agent ever
154
+ seeing them. Results and errors are redacted, values are bound to the site's origins, and the
155
+ form is submitted only when the identity opts in. turno-browser's API is now 1.1, which this
156
+ turno requires.
157
+ - aa7e39e: An output contract for scripts, hooks and agents:
158
+
159
+ - Every `--json` object carries `schemaVersion` (each element, for a list); no existing key
160
+ changed. `--json=fields` lists a command's fields, `--json=a,b` keeps only those, and an
161
+ unknown field is exit 2 with the list. Under `--json`, errors are one JSON line on stderr:
162
+ `{"schemaVersion":1,"error":{"code":"usage","exitCode":2,"message":"..."}}`.
163
+ - `turno limit show --watch --json` and the new `turno mcp top --watch --json` print NDJSON, one
164
+ record per line, like `turno mcp log --follow --json`.
165
+ - Exit codes: 0 ok, 1 failure, 2 usage, 3 no profile for the folder, 4 not signed in, 5 mcpd
166
+ down (`turno help exit-codes`). Changed: `turno auto` exits 3 (was 1) when the folder's
167
+ profile does not exist or there is no rule with `system = ""`; `turno mcp daemon status`,
168
+ `turno mcp top` and `turno mcp savings` exit 5 (was 1) when mcpd is down.
169
+ - `turno profile which --check` answers with that code and prints nothing when the folder has
170
+ a signed-in profile (`--agent` for other agents).
171
+ - turno's own state files are checked before use: a cut or hand-edited file reads as absent
172
+ instead of crashing, and an unreadable `mcp-managed.json` stops `turno mcp sync` and
173
+ `turno uninstall` with a message naming the file (they used to go on as if it were empty).
174
+ `turno identity log --verify` reports a line that is not an audit entry.
175
+ - `turno help environment` lists every variable turno reads and `turno help json` the JSON
176
+ rules; every command help ends with examples. Colors honor `CLICOLOR=0`, `CLICOLOR_FORCE`
177
+ and `TERM=dumb`; `TURNO_NO_UPDATE_NOTIFIER=1` turns the update check off.
178
+ - fa324c0: Cross-package contracts:
179
+
180
+ - turno-browser exports its public API as a typed `api` object with `API_VERSION` (1.0).
181
+ turno-cli checks it when it loads the package: a turno-browser that is too old (0.2 and older
182
+ have no `API_VERSION`) or too new stops `turno browser` and `turno identity browser:<id>`
183
+ with one line naming what to update, instead of failing later.
184
+ - mcpd sends every `tools/call`, from 2025-11-25 sessions and 2026-07-28 requests alike,
185
+ through one call middleware: the profile's tool filter, then the call log, then the session id.
186
+ Refusals and call log records are unchanged.
187
+ - Each relayed `tools/call` carries `_meta["io.turno/session"]`, an opaque id that is stable for
188
+ one agent session and different for every other. turno-browser-mcp hands it to its own tools
189
+ (`session` in their context); the Playwright tools are unaffected.
190
+ - cf4e077: Diagnostics and safe mode:
191
+
192
+ - `turno mcp call <server> [tool] [--args JSON] [--arg k=v|k:=json] [--profile p] [--json]`
193
+ calls a tool through mcpd as a profile's session in this folder would, or lists the tools.
194
+ Exits 1 on `isError` or a refused call, 5 when mcpd is down.
195
+ - `turno doctor --report` prints a Markdown block for an issue: turno, Node, OS, each agent's
196
+ version, mcpd, the findings and every path, with no tokens or secret values.
197
+ `turno config path --all` lists every path turno uses.
198
+ - Safe mode: `turno run <p> --no-gateway`, `turno <p> --no-gateway`, `turno auto --no-gateway`,
199
+ or `TURNO_SAFE=1`, opens the agent with the profile's account but without the gateway entries,
200
+ the gateway token and (Claude Code) the status line and hooks.
201
+ - Copilot CLI and Cursor CLI gateway entries send the session folder (`X-Turno-Cwd-B64`), so
202
+ folder server sets apply to them without the process lookup. Run `turno mcp sync` to rewrite
203
+ existing entries.
204
+ - `system = ""` no longer becomes an empty profile name for the hub's gateway token; `turno
205
+ status` and `turno profile which` say "no profile" for folders without a rule.
206
+ - 5b46749: Browser lifecycle:
207
+
208
+ - `turno-browser-mcp` passes a generated Playwright MCP `--config` that closes Chrome after 15
209
+ minutes without a tool call, headed too; the next call opens it again with the same profile.
210
+ `TURNO_BROWSER_IDLE` changes the limit (`"10m"`, `"0"` keeps Chrome open); `--idle-timeout`
211
+ and a `--config` of your own still win. Flags and tool names are unchanged.
212
+ - On start it closes a Chrome that an earlier, killed run left open on the same profile (only
213
+ a Chrome browser process for exactly that profile whose parent is gone), and on stdin close,
214
+ SIGTERM or SIGHUP it closes Chrome within about 2.5 seconds, forcefully if needed.
215
+ - mcpd stops a quiet `session` server under critical memory pressure even while its session
216
+ lives; the next call starts it again. `turno mcp top` counts the process groups a server's
217
+ children lead, so a browser's helpers always count.
218
+ - Docs: one recommendation for browsers, a `shared` server with `exclusive = true` per identity
219
+ (the block `turno identity add` prints), instead of `scope = "session"`.
220
+ - 57641d4: `turno identity set browser:<id>` and `turno browser set <id>` take flags for every identity.json
221
+ key of the browser host: `--tabs-max`, `--tabs-popups`, `--tabs-park`, `--tabs-close` and
222
+ `--no-tabs` (tab governor), `--background-throttling`, `--settle`, `--block-trackers`,
223
+ `--block-types`, `--block-patterns` and `--no-block`, `--cache`, `--cache-max-size` and
224
+ `--no-cache`. A flag changes only its part of a group, an empty value removes a key, and a bad
225
+ value is refused with the flag's name. `set` takes `--json` (what changed, or with `--dry-run`
226
+ what would, and the resulting file), and `--dry-run` now validates like the real write.
227
+ `turno identity add browser:<id>` takes the same flags, and `show` lists the new settings.
228
+ - 4663312: Move MCP servers between machines, OAuth detection, Codex trust and next-step hints:
229
+
230
+ - `turno mcp export [--profile p] [--json]` prints mcp.toml without secret values: references
231
+ stay, literal secrets become `keychain:turno/<server>/<key>` names, and the top of the file
232
+ lists the `turno secret set` commands the other machine needs.
233
+ - `turno mcp import <file>` merges an export, a JSON file with `mcpServers` or a Codex
234
+ `config.toml` into mcp.toml, keeping its comments and existing servers (`--force` replaces
235
+ them). A preview until `--write`.
236
+ - With `--write`, both import forms mark remote servers that answer with an OAuth challenge as
237
+ `auth = "oauth"`.
238
+ - `turno profile assign` and `turno profile repair` write Codex `[projects."<folder>"]
239
+ trust_level = "trusted"` entries in Codex profiles for their folder rules, never changing an
240
+ existing entry.
241
+ - Commands that write end with a `Next:` line (`profile add`, `profile assign`, `mcp import
242
+ --write`, `mcp export`, `secret set`); `turno config set hints false` turns them off.
243
+
244
+ ### Patch Changes
245
+
246
+ - 2948759: The package homepage is now https://turno.wimo.dev.
247
+ - 7b77664: pnpm, bun and yarn are first-class install paths. `turno upgrade` and `turno version` recognize
248
+ them from their lockfile even under a custom `PNPM_HOME`, `BUN_INSTALL` or yarn global folder,
249
+ and treat `pnpm dlx` and `bunx` like `npx`: a one-off copy has nothing to upgrade, and
250
+ `turno upgrade` says which command runs the newest release instead of installing turno globally.
251
+ Launchers and the status line refuse to point into any of those caches. `turno browser` and
252
+ `turno identity` find a `turno-browser` that pnpm 11 or later installed in its own global group.
253
+ - cf29953: The example time zone in the message for an invalid identity.json and in the help of
254
+ `turno identity` is now `Europe/Madrid`.
255
+ - 5566437: Every package has a README that tells the same story as the site. turno-cli's follows the
256
+ order of turno.wimo.dev and lists what the browser gained; turno-browser's is organized around
257
+ what the package does (identities, the credential vault, session export and import, tab limits,
258
+ `browser_batch`, blocking and cache, health and doctor); turno-core's says what the shared
259
+ package is for; turno-fonts' shows the status line and how `turno ui install` uses the font.
260
+ Each links to its page on turno.wimo.dev and to the releases.
261
+ - a0bfce8: New package `turno-core` with what turno-cli and turno-browser share: turno's paths, the secret
262
+ store (macOS Keychain, Linux Secret Service) and the process helpers. Both packages
263
+ now depend on it instead of keeping their own copies; behavior is unchanged.
264
+ - Updated dependencies [2948759]
265
+ - Updated dependencies [5566437]
266
+ - Updated dependencies [a0bfce8]
267
+ - turno-core@0.1.0
268
+
3
269
  ## 0.2.0
4
270
 
5
271
  ### Minor Changes
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
  </p>
7
7
 
8
8
  <p align="center">
9
- <b>One MCP gateway and per-folder accounts for Claude Code, Codex, Copilot CLI and Cursor CLI.</b>
9
+ <b>Switch accounts. Keep everything else.</b>
10
10
  </p>
11
11
 
12
12
  <p align="center">
@@ -17,15 +17,32 @@
17
17
  </p>
18
18
 
19
19
  <p align="center">
20
- English · <a href="https://github.com/wimo-dev/turno/blob/main/README.es.md">Español</a>
20
+ <a href="https://turno.wimo.dev"><b>turno.wimo.dev</b></a> · <a href="https://turno.wimo.dev/docs">Docs</a> · <a href="https://turno.wimo.dev/docs/releases">Releases</a> · English · <a href="https://github.com/wimo-dev/turno/blob/main/README.es.md">Español</a>
21
21
  </p>
22
22
 
23
- Every coding-agent session starts its own copy of every MCP server. Eight sessions with six
24
- common servers is **3,163 MiB in 56 processes**. turno starts each server once,
25
- only when a tool is called, behind one local gateway that every session of every agent shares:
26
- **847 MiB while all six run, 103 MiB while they sit idle**
27
- ([benchmark](https://github.com/wimo-dev/turno/blob/main/BENCHMARKS.md)). It also gives each folder its own account, so work repositories
28
- open with your work login and everything else with your personal one.
23
+ **Switching accounts? Keep talking.** The same session continues on your other account, with
24
+ its whole context, its MCP servers already signed in and a browser profile that keeps its
25
+ sign-ins. turno is for people who use a work account and a personal account with their coding
26
+ agents.
27
+
28
+ - **Your conversation.** A Claude Code session started with one account continues under
29
+ another, or forks into a second one: `turno session handoff work` prints the command.
30
+ - **Your MCP sign-ins.** One local gateway logs in to each remote OAuth server once per account
31
+ (`turno mcp login <server>`), and every agent session of that account reaches it through the
32
+ gateway.
33
+ - **Your browser session.** A real Chrome profile per identity that keeps its sign-ins (the
34
+ separate `turno-browser` package), and claude.ai links that open with the session's account
35
+ (`turno open`).
36
+ - **Your control.** Three skills of the Claude Code plugin move work between accounts from
37
+ inside a session: `/switch-account`, `/fork-session` and `/copy-artifact`.
38
+ - **The right account by itself.** Each project folder gets its account, in Claude Code, Codex,
39
+ Copilot CLI and Cursor CLI.
40
+ - **Easy to try, easy to undo.** `npx turno-cli demo` runs in a throwaway HOME, and
41
+ `turno undo` puts back every file a command changed.
42
+
43
+ The same gateway starts each MCP server once and shares it between sessions; the measured
44
+ memory saving is in [Benchmark](#benchmark). [turno.wimo.dev](https://turno.wimo.dev) tells the
45
+ whole story, with a small working picture of each part.
29
46
 
30
47
  ![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
48
 
@@ -33,29 +50,55 @@ open with your work login and everything else with your personal one.
33
50
 
34
51
  ```sh
35
52
  npx turno-cli demo # try it first, in a throwaway HOME; your own setup is not touched
36
- npm install --global turno-cli # macOS or Linux, Node 22.11+
37
- brew tap wimo-dev/turno && brew trust wimo-dev/turno && brew install turno # or Homebrew
38
53
  ```
39
54
 
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.
55
+ Then install it with the package manager you already use (macOS or Linux, Node 22.11+):
56
+
57
+ ```sh
58
+ npm install --global turno-cli
59
+ pnpm add --global turno-cli
60
+ bun add --global turno-cli
61
+ yarn global add turno-cli # yarn 1 (classic); yarn 2 and later have no global installs
62
+ brew tap wimo-dev/turno && brew trust wimo-dev/turno && brew install turno
63
+ ```
64
+
65
+ The npm package is `turno-cli`; the command it installs is `turno`, and `turno upgrade` later
66
+ updates it with the same tool. `npx turno-cli`, `pnpm dlx turno-cli` and `bunx turno-cli` run it
67
+ once without installing. It runs no install scripts, and npm and Homebrew install exactly the
68
+ dependency versions that were tested, from its `npm-shrinkwrap.json` (pnpm, bun and yarn resolve
69
+ the dependencies of its dependencies themselves). CI installs it each of these ways on macOS and
70
+ Linux. Nothing leaves your machine: no account, no telemetry, no proxy for model traffic.
44
71
 
45
72
  ## What it does
46
73
 
74
+ - **A conversation that continues on another account.** Your Claude Code profiles share
75
+ conversations, skills, commands, hooks, plugins and settings, and keep only their own login.
76
+ `turno work --resume <id>` continues a session that another account started, and
77
+ `turno session handoff work` prints the exact command (`--fork` keeps this session open and
78
+ starts a copy). [What profiles share](https://turno.wimo.dev/docs/concepts/profiles).
79
+ - **MCP sign-ins, once per account.** The gateway logs in to each OAuth remote server once per
80
+ account (`turno mcp login <server>`) and every agent session of that account uses it; a
81
+ variant per profile lets work and personal reach two accounts of the same service. Secrets
82
+ live in the macOS Keychain or the Linux Secret Service, not in agent configs.
83
+ [The gateway](https://turno.wimo.dev/docs/concepts/gateway).
84
+ - **A browser per identity** (separate package `turno-browser`): an MCP server that drives your
85
+ installed Chrome with one persistent profile per identity, so an agent works in the sessions
86
+ you signed into by hand, and `turno open <profile> <url>` opens a claude.ai link with the
87
+ account that owns it. See [Browser with real profiles](#browser-with-real-profiles).
88
+ - **Skills that move work between accounts.** The Claude Code plugin adds `/switch-account`,
89
+ `/fork-session` and `/copy-artifact`, and the accounts bridge lets a session delegate a task to
90
+ a service only another profile is signed into, asking before it writes.
91
+ [Skills](https://turno.wimo.dev/docs/concepts/skills).
92
+ - **The folder picks the account.** `turno profile assign ~/code/acme work` and every agent you
93
+ open in that repository uses your work login; `turno auto` picks it and says which account and
94
+ why, and `turno status` shows who is logged in where. The same folder rule can choose which
95
+ MCP servers sessions there see. [Folder rules](https://turno.wimo.dev/docs/concepts/folder-rules).
47
96
  - **One MCP gateway for every session.** `mcpd` listens on `127.0.0.1`, answers `initialize` and
48
97
  the tool lists from a cache, starts a server the first time one of its tools is called, shares
49
98
  that process between sessions where it is safe (`shared`, `project` or `session` scope) and
50
99
  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
58
- profiles, so `turno work --resume <id>` continues a session started with another account.
100
+ same endpoint, and `turno mcp log`, `top` and `savings` show its calls, memory and saving. See
101
+ [docs/mcp.md](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md).
59
102
  - **Four agents, one setup.** The same profiles, folder rules and gateway for:
60
103
 
61
104
  | Agent | Profile | Gateway entries | Example |
@@ -65,13 +108,16 @@ traffic.
65
108
  | GitHub Copilot CLI | `~/.copilot-<p>`, `copilot-<p>` | `mcp-config.json` | `copilot-work` |
66
109
  | Cursor CLI | `~/.cursor-<p>`, `cursor-agent-<p>` | `~/.cursor/mcp.json`, routed by environment | `cursor-agent-work` |
67
110
 
68
- opencode, Gemini CLI, Goose, Crush, Droid and Kiro can use the gateway too:
69
- `turno mcp config --agent <name>` prints their entries. See [docs/agents.md](https://github.com/wimo-dev/turno/blob/main/docs/agents.md).
111
+ A profile is one account of one agent. opencode, Gemini CLI, Goose, Crush, Droid and Kiro can
112
+ use the gateway too: `turno mcp config --agent <name>` prints their entries. See
113
+ [docs/agents.md](https://github.com/wimo-dev/turno/blob/main/docs/agents.md).
70
114
  - **A status line** for Claude Code with the account, its 5 h and weekly usage, context, branch
71
115
  and cost, with Nerd Font icons it installs for you (or Unicode where there is none).
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.
116
+ - **Easy to check, easy to undo.** `turno doctor` names each problem and its fix (`--fix`
117
+ repairs what is safe, `--report` prints a block for an issue with no secrets), `turno mcp call`
118
+ tries a tool the way a session would, `--no-gateway` opens the agent without turno's gateway to
119
+ tell whose problem it is, and `turno undo` puts back every file a command changed.
120
+ [Troubleshooting](https://turno.wimo.dev/docs/troubleshooting).
75
121
 
76
122
  ## Quick start
77
123
 
@@ -188,25 +234,43 @@ change, and print the `turno undo <stamp>` that puts them back. `turno mcp impor
188
234
  | `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 |
189
235
  | `turno <profile> [args]`, `turno run <profile\|auto> [args]` | the profile's agent with that account (args pass through) |
190
236
  | `turno auto [--agent codex\|copilot\|cursor]` | the profile assigned to the current folder |
191
- | `turno profile list\|add\|repair\|remove\|which\|assign\|unassign` | the profiles, and which folders use each |
237
+ | `turno profile list\|add\|repair\|remove\|which [--check]\|assign\|unassign` | the profiles, and which folders use each; `which --check` exits 0, 3 or 4 for scripts |
192
238
  | `turno mcp list\|sync\|config\|import\|install\|refresh\|doctor` | the MCP gateway's servers, and entries for other agents |
239
+ | `turno mcp export [--profile p]`, `turno mcp import <file>` | move servers to another machine, secrets by name only |
240
+ | `turno mcp call <server> [tool]` | list a server's tools or call one through mcpd, as a profile's session here would |
193
241
  | `turno mcp login\|logout <server>` | log mcpd in to an OAuth remote server, once per account |
194
242
  | `turno mcp log\|top\|savings` | the gateway's tool call log, memory per server, and what it saves |
195
243
  | `turno mcp daemon start\|stop\|restart\|status\|logs`, `turno mcp token rotate` | the gateway service, and its token |
196
244
  | `turno status [--json]` | one screen: this folder, profiles and usage, sessions, mcpd, and the next step |
197
- | `turno limit show [--watch]\|set\|clear` | usage windows per account, and exhausted marks |
245
+ | `turno limit show [--watch] [--json]\|set\|clear` | usage windows per account, and exhausted marks; `--watch --json` prints NDJSON |
198
246
  | `turno session list\|handoff <p> [--fork]` | open sessions, and the command to continue this one under another profile |
199
247
  | `turno open [profile] <url>` | open an http(s) or mailto link; claude.ai links use that profile's Chrome profile |
200
248
  | `turno identity list\|add\|remove\|login\|prefer\|log [--verify]` | service accounts for the bridge, browser identities, the audit log |
201
249
  | `turno secret set\|has\|rm\|list` | MCP secrets in the macOS Keychain or the Linux Secret Service |
202
250
  | `turno ui status\|install` | the status line, its font and icons in every terminal |
203
251
  | `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 |
204
- | `turno config path\|get\|set\|unset\|edit\|check` | config.toml without losing its comments |
252
+ | `turno doctor --report`, `turno run <p> --no-gateway` | a Markdown block for an issue (no secrets); the agent without turno's gateway, to tell whether a problem is turno's |
253
+ | `turno config path [--all]\|get\|set\|unset\|edit\|check` | config.toml without losing its comments; `path --all` lists every path turno uses |
205
254
  | `turno undo [--list] [<stamp>\|last]`, `turno undo --prune` | put back the files a command changed; prune old backups |
206
255
  | `turno upgrade [--check]`, `turno version` | update turno the way it was installed |
207
256
  | `turno uninstall [--dry-run] [--yes] [--keep-config] [--purge]` | remove what turno set up (profile folders stay); `--purge` also removes its state and caches |
208
257
  | `turno completion zsh\|bash\|fish` | shell completion, including profiles and config keys |
209
- | `turno browser bench` | developer diagnostic: browser engine compatibility (needs `turno-browser`) |
258
+ | `turno browser identities\|add\|show\|set\|login\|remove` | browser identities and their settings (needs `turno-browser`) |
259
+ | `turno browser vault add\|list\|remove\|submit` | sign-in credentials per site in the OS secret store, filled by the `browser_login` tool |
260
+ | `turno browser export <id> --out <file>`, `turno browser import <file>` | move an identity's session to another machine as one encrypted file |
261
+ | `turno browser flows\|replay <id>`, `turno browser record\|traces <id>` | saved flows and replaying them; opt-in recordings (flows, traces, screenshots) and the trace viewer |
262
+ | `turno browser doctor [--fix]`, `turno browser reputation [<id>]` | check Chrome and every identity; how often each site challenged it |
263
+ | `turno browser bench` | developer diagnostic: browser engine compatibility |
264
+
265
+ For scripts and hooks: every `--json` object carries `schemaVersion`, `--json=fields` lists the
266
+ fields and `--json=name,email` keeps only those, `--watch --json` prints one JSON record per
267
+ line, and under `--json` an error is one JSON line on stderr (`turno help json`). Exit codes
268
+ are 0 ok, 1 failure, 2 usage, 3 no profile for the folder, 4 not signed in, 5 mcpd down
269
+ (`turno help exit-codes`); `turno profile which --check` answers with them, for example
270
+ `turno profile which --check || turno profile assign . work`. `turno help environment` lists
271
+ every variable turno reads, colors included (`NO_COLOR`, `FORCE_COLOR`, `CLICOLOR`,
272
+ `CLICOLOR_FORCE`, `TERM=dumb`). Commands that write end with a `Next:` line that says what to
273
+ run after them (never under `--json`); `turno config set hints false` turns those lines off.
210
274
 
211
275
  ### Config
212
276
 
@@ -257,7 +321,6 @@ scope = "shared" # one process for every session
257
321
  [server.devtools]
258
322
  command = "chrome-devtools-mcp"
259
323
  scope = "session" # one per agent session, stopped when it ends
260
- idle = "15m"
261
324
 
262
325
  [server.issues]
263
326
  command = "issues-mcp"
@@ -286,12 +349,36 @@ turno identity add browser:school # an identity and its mcp.toml entry
286
349
  turno identity login browser:school # sign in by hand once; cookies persist
287
350
  ```
288
351
 
289
- It drives the installed Google Chrome, headed, with a persistent profile per identity and no
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).
352
+ `turno-browser` is its own MCP server. It drives the installed Google Chrome, headed, with a
353
+ persistent profile per identity and no injected scripts; each identity keeps its time zone,
354
+ languages and locale fixed (`turno browser show|set <id>`).
355
+
356
+ - **It cleans up after itself.** At most 8 tabs per session's browser, an unused tab is parked
357
+ after 5 minutes and closed after 15, and popups nobody asked for are closed. Chrome closes
358
+ after 15 minutes without a tool call and opens again on the next one, and mcpd stops the
359
+ server after 30 (see [Browsers](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md#browsers)). When the agent ends, Chrome closes with
360
+ it, and a Chrome that a killed run left open is closed on the next start.
361
+ - **Fewer round trips.** `browser_batch` runs up to 20 actions in one call, and an action that
362
+ fails says which element covers the target, or that it is hidden, disabled or gone.
363
+ - **Sign-ins the agent never sees.** `turno browser vault add` keeps a username, a password and
364
+ an optional TOTP secret per site in the OS secret store, and the `browser_login` tool fills
365
+ them into that site's sign-in page; results are redacted and values are bound to the site.
366
+ - **Sessions you can move.** `turno browser export <id> --out <file>` writes an identity's
367
+ cookies and storage as one file encrypted with a passphrase, with an expiry, and
368
+ `turno browser import <file>` reads it on another machine. The vault never leaves.
369
+ - **Lighter pages, when you want them.** Per identity and off by default: block trackers,
370
+ images, media or fonts, and keep static resources in a cache on disk.
371
+ - **Health you can read.** `turno browser doctor [--fix]` checks Chrome and every identity, and
372
+ `turno browser reputation` shows how often each site challenged it.
373
+
374
+ More in [Browser identities](https://turno.wimo.dev/docs/concepts/browser-identities) and
375
+ [`turno browser`](https://turno.wimo.dev/docs/reference/cli/browser).
291
376
 
292
377
  **Acceptable use.** Use it with your own accounts, on sites whose terms allow automated access
293
- by you, and at a human pace. Do not use it to get around access controls, paywalls, CAPTCHAs or
294
- rate limits, to scrape at scale, or to access accounts that are not yours.
378
+ by you, and at a human pace. Do not use it to get around access controls, paywalls or rate
379
+ limits, to scrape at scale, or to access accounts that are not yours. Captcha solving and natural
380
+ language actions are off unless you turn them on per identity; both send page content to a third
381
+ party you pick, and captcha solving may break a site's terms.
295
382
 
296
383
  ### Accounts bridge
297
384
 
@@ -319,7 +406,8 @@ Details: [docs/ui.md](https://github.com/wimo-dev/turno/blob/main/docs/ui.md).
319
406
  ### Claude Code plugin
320
407
 
321
408
  `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
409
+ claude.ai artifact (with its files and assets) from one profile's account to another, a
410
+ `browser-identity` skill that drives a browser identity with `turno browser do`, and a hook
323
411
  that records when a profile reaches its usage limit, so `turno status` can show it:
324
412
 
325
413
  ```
@@ -372,7 +460,7 @@ that `turno undo` restores, and `turno uninstall` removes what it set up.
372
460
 
373
461
  Interactive commands ask the npm registry for a newer version at most once a day, sending only
374
462
  the package name. Turn it off with `update_check = false` in config.toml, `DO_NOT_TRACK=1`,
375
- `NO_UPDATE_NOTIFIER=1` or `TURNO_NO_UPDATE_CHECK=1`; it is also off in CI and outside a
463
+ `NO_UPDATE_NOTIFIER=1`, `TURNO_NO_UPDATE_CHECK=1` or `TURNO_NO_UPDATE_NOTIFIER=1`; it is also off in CI and outside a
376
464
  terminal. Apart from that, turno only goes online when you ask it to: `turno ui install`
377
465
  downloads the status line font, `turno mcp install` and `turno upgrade` fetch packages from npm,
378
466
  `turno mcp import --write` and `turno init` (once you confirm) ask npm for the command name of
@@ -393,11 +481,15 @@ pnpm check # typecheck, lint (Biome, knip), tests (sandboxed HOME), text r
393
481
  pnpm test:e2e # also the end-to-end test that needs the network (Cursor)
394
482
  ```
395
483
 
396
- Design: [docs/design](https://github.com/wimo-dev/turno/blob/main/docs/design/2026-11-12-claudio-ecosystem-design.md). Decisions:
397
- [docs/decisions](https://github.com/wimo-dev/turno/blob/main/docs/decisions/). Progress: [docs/STATUS.md](https://github.com/wimo-dev/turno/blob/main/docs/STATUS.md).
398
-
399
484
  ## License
400
485
 
401
486
  Apache License 2.0 ([LICENSE](https://github.com/wimo-dev/turno/blob/main/LICENSE), [NOTICE](https://github.com/wimo-dev/turno/blob/main/NOTICE)). The bundled fonts keep their own
402
487
  licenses ([packages/fonts/LICENSE.txt](https://github.com/wimo-dev/turno/blob/main/packages/fonts/LICENSE.txt)); dependencies are listed in
403
- [THIRD_PARTY_NOTICES.md](https://github.com/wimo-dev/turno/blob/main/THIRD_PARTY_NOTICES.md). Made in Monterrey, Mexico.
488
+ [THIRD_PARTY_NOTICES.md](https://github.com/wimo-dev/turno/blob/main/THIRD_PARTY_NOTICES.md).
489
+
490
+ ## Documentation
491
+
492
+ [turno.wimo.dev](https://turno.wimo.dev) is the site: a landing page that tells the story in
493
+ eight parts, and the [docs](https://turno.wimo.dev/docs) in three areas: guides by problem and
494
+ concepts, the reference generated from the code, and one troubleshooting page per `turno doctor`
495
+ finding, with a filter. English and Spanish. Its source is in [apps/docs](https://github.com/wimo-dev/turno/blob/main/apps/docs).
@@ -1,7 +1,18 @@
1
1
  import { createHash } from "node:crypto";
2
- import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, rmdirSync, statSync, writeSync } from "node:fs";
2
+ import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, rmdirSync, statSync, writeSync, } from "node:fs";
3
3
  import { dirname } from "node:path";
4
4
  import { PRIVATE_FILE_MODE, ensurePrivateDir, paths } from "../core/paths.js";
5
+ import { hasFields, parseState } from "../core/state-file.js";
6
+ /** One line of audit.jsonl as `turno identity log` reads it (state-file.ts). */
7
+ const isAuditEntry = (v) => hasFields(v, {
8
+ ts: "string",
9
+ caller: "object",
10
+ account: "string",
11
+ outcome: "string",
12
+ task: "string",
13
+ durationMs: "number",
14
+ }) &&
15
+ (v.prev === undefined || typeof v.prev === "string");
5
16
  const TASK_LIMIT = 500;
6
17
  /** `prev` of the first chained line of an empty log. */
7
18
  export const GENESIS = "0".repeat(64);
@@ -124,12 +135,10 @@ export function readAudit(limit = 20, env = process.env) {
124
135
  for (const line of text.split("\n")) {
125
136
  if (!line.trim())
126
137
  continue;
127
- try {
128
- out.push(JSON.parse(line));
129
- }
130
- catch {
131
- /* skip */
132
- }
138
+ // A line that is not an audit entry (cut short, edited by hand) is skipped; --verify reports it.
139
+ const r = parseState(line, isAuditEntry, 1, "audit line");
140
+ if (r.ok)
141
+ out.push(r.value);
133
142
  }
134
143
  return limit > 0 ? out.slice(-limit) : out;
135
144
  }
@@ -159,13 +168,14 @@ export function verifyAudit(env = process.env) {
159
168
  continue;
160
169
  lines++;
161
170
  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
- }
171
+ const parsed = parseState(line, isAuditEntry, 1, "line");
172
+ if (!parsed.ok)
173
+ return fail(parsed.problem === "corrupt"
174
+ ? "not valid JSON"
175
+ : parsed.problem === "newer"
176
+ ? "written by a newer turno"
177
+ : "not an audit entry");
178
+ const entry = parsed.value;
169
179
  if (entry.prev === undefined) {
170
180
  if (chained)
171
181
  return fail("line without a hash after the chain started (added by hand?)");
@@ -174,7 +184,9 @@ export function verifyAudit(env = process.env) {
174
184
  else {
175
185
  const expected = prevLine === undefined ? GENESIS : lineHash(prevLine);
176
186
  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)");
187
+ return fail(prevLine === undefined
188
+ ? "first line does not start the chain (lines removed from the start?)"
189
+ : "hash does not match the previous line (edited, removed or reordered)");
178
190
  chained = true;
179
191
  }
180
192
  prevLine = line;