wherdr 2.5.0 → 2.6.0

package/docs/installation.md

@@ -58,7 +58,7 @@ The script ([read it first](https://wherdr.dev/install), source in
    Mac with Homebrew, otherwise the official Node.js 22 build from nodejs.org, its checksum
    checked, unpacked in `~/wherdr/node` (used by wherdr only: your `PATH` is not changed). With
    musl libc (Alpine) it gives the install links instead;
-4. runs `herdr plugin install afloury/wherdr --yes`: the [Herdr plugin](plugins.md#install-as-a-herdr-plugin)
+4. runs `herdr plugin install afloury/wherdr --ref 2.x --yes`: the [Herdr plugin](plugins.md#install-as-a-herdr-plugin)
    downloads the GitHub release package of its version (checksum checked, no wait for npm),
    installs it in `~/wherdr/app`, starts it on `http://localhost:7683`, opens the setup guide in
    your browser (first install) and binds **prefix+i** to its panel;
@@ -87,7 +87,7 @@ Settings, as environment variables (`curl -fsSL https://wherdr.dev/install | WHE
 | `WHERDR_SERVICE` | — | `off`: no login service; wherdr then starts with Herdr only (the plugin's startup hook). |
 | `WHERDR_YES` | — | `1` answers yes to every question (non-interactive use), installing Node.js included. |
 | `WHERDR_NO_BROWSER` | — | `1` never opens a browser. |
-| `WHERDR_REF` | main | Git tag or branch of the plugin. |
+| `WHERDR_REF` | `2.x` | Git tag or branch of the plugin (`2.x` is the wherdr 2 release branch). |
 | `WHERDR_PLUGIN` | `afloury/wherdr` | A local checkout to link and build instead (development, tests). |
 
 Update: run the command again (it offers the update), **U** in the wherdr panel, or **Update** in
@@ -134,6 +134,13 @@ home screen and in Settings › About, with the release notes and the exact comm
 Hide it until the next version with ×. Set `WHERDR_UPDATE_CHECK=off` to disable the check. The
 installed version is shown in Settings › About.
 
+Updates stay within the running major version: wherdr 2 only offers 2.x releases, and the
+one-tap update refuses to install a new major. When wherdr 3 is published, the home screen shows
+a **“wherdr 3 is out”** card instead of the banner, with its release notes, its migration guide and a
+Copy button for the command that installs wherdr 3 **beside** wherdr 2 (it only prints its plan
+until you add `--yes`). wherdr 2 keeps running with its data, and 2.x fixes are still offered in
+Settings › About.
+
 GitHub release packages (including the bundled agent skill) and Homebrew
 updates are published without waiting for npm moderation. Native plugin installs and updates
 use the GitHub `.tgz` and verify its SHA-256 checksum before extraction. A failed one-tap
@@ -142,7 +149,9 @@ GitHub first, then the prebuilt npm package of the exact same version (with its
 This also keeps older 1.3.x releases without GitHub archives installable with Node.js or Bun.
 Packages predating the bundled skill retain the plugin checkout's commands and skill, so
 skill refresh, installation and uninstallation remain available.
-The installer fetches `main` explicitly unless you set `WHERDR_REF`.
+The installer fetches the `2.x` branch unless you set `WHERDR_REF`. The plugin update command
+adds `--ref 2.x`, and a git checkout follows `2.x` (`git checkout 2.x`) before pulling: `main`
+holds wherdr 3.
 
 The SHA-256 checksum detects damaged downloads. It is served beside the archive, so someone
 who can replace both files can make them match; it does not prove the publisher’s identity
@@ -175,10 +184,10 @@ and the app says so. Every step is logged in `~/wherdr/update.log`.
 | Setup | Update command (in the wherdr folder) |
 | --- | --- |
 | The one command | Run `curl -fsSL https://wherdr.dev/install \| sh` again: it offers the update (GitHub release package) |
-| Herdr plugin, Node.js | **U** in the **wherdr** panel, or `herdr plugin install afloury/wherdr --yes` (wherdr restarts on the new version) |
+| Herdr plugin, Node.js | **U** in the **wherdr** panel, or `herdr plugin install afloury/wherdr --ref 2.x --yes` (wherdr restarts on the new version) |
 | `wherdr` command (npm) | `npm install -g wherdr@latest && wherdr restart` (npx: stop it, then `npx wherdr@latest`) |
 | `wherdr` command (Homebrew) | `brew upgrade wherdr`, then `brew services restart wherdr` |
-| From source | `git pull && npm ci && npm run build`, then restart wherdr |
+| From source | `git checkout 2.x && git pull && npm ci && npm run build`, then restart wherdr |
 
 Update notices also show the number of newer stable releases and up to four
 additional version numbers besides the latest. This measures published releases,

package/docs/networks.md

@@ -26,7 +26,10 @@ tailscale serve --bg --https=7683 http://127.0.0.1:7683
 ```
 
 Tailscale Serve listens on HTTPS port 7683 of your tailnet name, with a valid certificate, and
-forwards to wherdr's local HTTP port. Only devices of your tailnet can reach it.
+forwards to wherdr's local HTTP port. Only devices of your tailnet can reach it, and wherdr
+answers only **your own** devices among them: another user's device in a team tailnet, a node
+shared in from another tailnet or a tagged node is refused until you set up a passkey (see
+[Your own devices only](security.md#own-devices)).
 
 **wherdr enables that address by itself**, on a server without a screen too: at startup, every
 30 seconds, and when an address it does not know yet is opened, it reads what `tailscale serve`
@@ -59,9 +62,11 @@ desktop layout can replace the Herdr terminal client for daily work.
 **5. Passkey lock** (optional): Settings → Security → **Enable passkey lock**. The
 first passkey asks for a bootstrap token, printed in the server log (`~/wherdr/wherdr.log`,
 **L** in the wherdr panel); it changes on each restart and is only needed for that first passkey. Add a passkey on each of
-your devices after that (see [New device](security.md#new-device)). Without one, every device of your
-tailnet can control your agents: enough when the tailnet is yours alone, a passkey adds a lock
-on each device when someone else shares the tailnet or your devices.
+your devices after that (see [New device](security.md#new-device)). Without one, wherdr
+answers this computer and your own tailnet devices; devices of other people on your tailnet are
+always refused (with a passkey, they reach the lock screen). A passkey adds an automatic lock on
+each device if you want one, for example on a computer other people log in to (see
+[Shared computers](security.md#shared-computers)).
 
 **6. More machines** (optional): register your other computers in Herdr over SSH
 (`herdr machine add`, see [Several machines (SSH)](machines.md#several-machines-ssh)). Their agents show

package/docs/plugins.md

@@ -7,7 +7,7 @@
 This is what [the one command](installation.md#the-one-command) installs; you can also run it yourself, on Linux
 and macOS, with Herdr ≥ 0.9.1 (no checks for Herdr or Node.js first). In three lines:
 
-1. Run `herdr plugin install afloury/wherdr`: it installs wherdr, starts it
+1. Run `herdr plugin install afloury/wherdr --ref 2.x`: it installs wherdr, starts it
    (`✓ wherdr is running → http://localhost:7683`) and, at the first install on a computer with a
    screen, opens the setup guide in your browser (`open` on macOS, `xdg-open` on Linux with a
    display; a headless server, or `WHERDR_NO_BROWSER=1` in the environment of the install, just

package/docs/quick-start.md

@@ -33,20 +33,21 @@ address and the phone steps instead. See [The one command](installation.md#the-o
 
 **wherdr 2.0 runs only natively**, as your user, so it can act on the
 [herdr-projects Board](board.md#works-great-with-herdr-projects) (Coordinator, reply, start, stop,
-approve). Other ways, after it: `herdr plugin install afloury/wherdr` (the same plugin, without
+approve). Other ways, after it: `herdr plugin install afloury/wherdr --ref 2.x` (the same plugin, without
 the checks), and [the `wherdr` command](command.md#the-wherdr-command) from npm or Homebrew (npm can hold a
 new release for up to two days; the installer gets it from GitHub at once).
 
 At first launch, wherdr opens a **setup guide**: the Herdr agents it found, your phone
-(Tailscale), then the passkey lock and notifications. Skip it any time; finishing or skipping is
+(Tailscale), then notifications. Skip it any time; finishing or skipping is
 saved on the server (`data/onboarding.json`), so your other devices do not show it again. Reopen
 it from Settings › About › **Setup guide**. On a phone that already opens wherdr through its
 tailnet address, the phone step becomes Add to Home Screen.
 
-**Passkeys are tied to the address they are created on.** Once wherdr's tailnet address is
-published and answers, the guide opened on `localhost` shows **Continue on
-<machine>.<tailnet>.ts.net**, which reopens it at the same step on that address, and its Security
-step (like Settings › Security) sends the passkey lock there. Nothing redirects on its own:
+Once wherdr's tailnet address is published and answers, the guide opened on `localhost` shows
+**Continue on <machine>.<tailnet>.ts.net**, which reopens it at the same step on that address
+(notifications and the installed app need it). The guide does not propose a passkey: the
+optional passkey lock is in Settings › Security, which also sends it to that address, since
+**passkeys are tied to the address they are created on**. Nothing redirects on its own:
 `localhost` stays valid on the computer. The installer, the Herdr plugin and `wherdr open` open
 that address too when it is already published.
 

package/docs/quotas.md

@@ -30,9 +30,12 @@ week, with reset times), for every online machine.
 
 - **Codex**: nothing to do, Codex writes its limits in its session files. Machines on different
   Codex accounts get one block each (told apart by a short hash of the account ID found in the
-  session files; `~/.codex/auth.json` is never read). If a session has no recognized account
-  fingerprint, its reading stays under its own machine and is never merged with another
-  conversation or machine. A new conversation identifies an account switch even before it
+  session files; `~/.codex/auth.json` is never read). Codex only writes that account ID in
+  conversations created with a ChatGPT login by a recent Codex version. A reading without it
+  joins another machine's reading only when both show the same 5-hour window and the same
+  weekly window (resets within a minute, week already started), a sign of one account: the
+  machines then share one Codex row at the top, like Claude. Otherwise it stays under its own
+  machine and is never merged with another conversation or machine. A new conversation identifies an account switch even before it
   logs limits; until a reading for that account is available, no Codex gauge is shown. Failed reads do not
   reuse an older machine snapshot, and remembered weekly limits cannot cross account
   identities. Without a known fingerprint, remembered weekly corrections are not reused,

package/docs/release-notes-2.6.0.md

@@ -0,0 +1,29 @@
+## New
+
+2.6 is the last new version of wherdr 2. It gets you ready for wherdr 3, which installs **beside** wherdr 2 rather than replacing it.
+
+- **Updates stay on wherdr 2.** The update check only offers 2.x versions. When wherdr 3 is published, the Update button never installs it, and wherdr 2 fixes (2.6.1, 2.6.2…) are still offered.
+- **A "wherdr 3 is out" card.** Once wherdr 3 is released, Home shows a card instead of the update banner, with links to its release notes and its migration guide, and a Copy button for the command that installs wherdr 3 beside this version. That command shows its plan first and changes nothing until you add `--yes`. wherdr 2 keeps running with its data, so you can compare both and go back at any time.
+- **Installs follow the 2.x branch.** The Herdr plugin now updates from the `2.x` branch (**U** in the panel, and the update command, add `--ref 2.x`), and the curl installer installs `2.x` by default (`WHERDR_REF` still picks another branch or tag). If you run wherdr from a git checkout, switch it to the release branch once with `git checkout 2.x` before pulling; the update banner shows that command.
+- **SVG diagrams in conversations.** A static `svg` code block shows as a theme-aware preview you can enlarge or copy; unsafe or incomplete content stays plain code. Thanks to [@guileen](https://github.com/guileen).
+- **omp context at a glance.** Agent rows and the composer show how much of omp's context is used.
+
+## Improved
+
+- **Tighter security on the tailnet.** Without a passkey, only your own Tailscale devices can open wherdr; another user's device in a team tailnet, or a shared-in or tagged node, is refused until a passkey is set. A locked device learns nothing before unlocking (no passkey names, machine name or server clock). **Lock all devices** now invalidates every session, push subscription and open connection at once.
+- **Lighter conversation reads.** While an agent writes, wherdr reads only what was added to its transcript.
+
+## Fixed
+
+- A finished task's Agent tab shows the agent's conversation instead of the shell left behind.
+- Conversations reopen at their reading position, are not redrawn when nothing changed, and keep a sent message visible while reads fail for a while.
+- A repeated Enter (from a dictation app, for example) no longer sends the same message twice, and a single stray Escape no longer stops the agent.
+- Home counters and badges agree on task states, the Board grouping appears right after a reload, and two machines on one Codex account share one quota row.
+- Reconnecting after a suspend or a redeploy no longer hangs on a stalled read.
+- On macOS, when wherdr runs as a service, Settings › Phone no longer says *not connected* while Tailscale runs, and Web Push works.
+
+## Update
+
+No migration is required from 2.5.0. Node.js 22 or newer and Herdr 0.9.1 or newer remain required. Git checkouts: run `git checkout 2.x` once before your next `git pull`.
+
+[Full changelog](https://github.com/afloury/wherdr/blob/v2.6.0/CHANGELOG.md)

package/docs/security.md

@@ -10,7 +10,7 @@ wherdr drives Herdr, so **it can run anything as your user**.
   network** (Tailscale or [equivalent](networks.md#other-private-networks)). Never add a public route
   (port forwarding, public reverse proxy, ngrok…); the only exception is a Cloudflare Tunnel
   behind Cloudflare Access, with its risks (it needs `WHERDR_TRUSTED_NETWORKS=any`).
-- It answers only this computer and the tailnet: see [Network access](security.md#network-access).
+- It answers only this computer and your own tailnet devices: see [Network access](security.md#network-access).
 - Requests are accepted only for `localhost`, loopback addresses, the runtime's hostname, the
   hostname in `APP_URL`, the tailnet name `tailscale serve` publishes for wherdr's own port
   (read from Tailscale on the machine, never from a request, and only while it is published),
@@ -29,17 +29,37 @@ wherdr drives Herdr, so **it can run anything as your user**.
 
   A network error or a server restart never locks the app. **Lock all devices** (Settings →
   Security, for a lost or stolen device) ends every session, this one included, and keeps the
-  passkeys: each device unlocks again with its own. Turning the lock off removes the passkeys and
-  invalidates every session. Lost passkey: delete `data/auth.json` on the server; the app is open
-  again to whoever can reach it.
+  passkeys: each device unlocks again with its own. It draws a new signing secret and a new random
+  session generation, so even a cookie forged by someone who once read `data/auth.json` stops
+  working; open WebSockets close at once, and every push subscription is removed (a device
+  subscribes again by itself once unlocked; its own quiet setting is reset). Turning the lock off
+  does the same and removes the passkeys; every open app then posts its push subscription again
+  at once, and an app that was closed or asleep does so when it opens or reconnects. The first start after upgrading to this version ends the open
+  sessions once (the old numeric generation is replaced); the passkeys stay. Lost passkey: delete
+  `data/auth.json` on the server; the app is open again to whoever can reach it.
+- **Before the unlock**, a locked device only learns that the app is locked: no passkey names or
+  dates, no machine name, no server clock. Unlocking lists no key: the device offers its own
+  passkey for the site (passkeys are registered as discoverable credentials). Unlock attempts
+  are limited to 10 per minute per client, and at most 100 unlock challenges wait at once.
+- **Protected files**: the file browser and the file paths shown in conversations never preview,
+  download or stream wherdr's data folder (`DATA_DIR`, with `auth.json`, the push keys and
+  subscriptions), `~/.ssh` or `~/.config/herdr`, on any machine, even through a symlink or inside
+  a browsed project. Agents themselves can still read them: the lock protects the app, not the
+  machine.
 - <a id="new-device"></a>**New device**: it can only get in with an existing passkey. Unlock it
   with a passkey synced by your password manager (iCloud Keychain, Google Password Manager,
   1Password…), or with the passkey of another device through the browser's "use a phone or
   tablet" QR code, then Settings → Security → **Add this device** to give it its own passkey.
-- Without a passkey, **anyone who can reach the address can control your agents**: every device
-  on your tailnet, and every user of your tailnet if you share it.
+- By default, with no passkey, wherdr answers **this computer and your own tailnet devices**:
+  devices of other people on your tailnet are always filtered out (no setting turns this off).
+  Whoever uses this computer or one of your devices can control your agents, other OS users of
+  this computer included (see [Shared computers](security.md#shared-computers)). The passkey is
+  optional: it adds an automatic lock on each device if you want one, and then lets other
+  people's tailnet devices reach that lock.
 - Writes require `Content-Type: application/json` (or `image/*` for photos, `application/octet-stream` for attached files) and an `Origin`
-  matching the host, WebSockets included. API reads sent from another site (links, images,
+  matching the host, WebSockets included. Request bodies are read with a size limit (256 KB for
+  JSON, 20 MB for photos, 30 MB for attached files), chunked bodies included: past it the server
+  stops reading, answers `too_large` and closes the connection. API reads sent from another site (links, images,
   `no-cors` fetches, reported by the browser's `Sec-Fetch-Site`) are refused too.
 - A strict Content Security Policy limits scripts to the app's own origin and hashed inline
   scripts, and connections to that origin and its WebSockets. It also blocks embedded objects
@@ -58,17 +78,19 @@ See [SECURITY.md](../SECURITY.md) to report a vulnerability.
 
 ### Network access
 
-wherdr answers **this computer and your tailnet only**. A device on any other network (a coffee shop
+wherdr answers **this computer and your own tailnet devices only**. A device on any other network (a coffee shop
 Wi-Fi, an office LAN, the Internet) gets HTTP 403 (`network`), with a page that says why, even
-when it knows the address and the port. The passkey lock is never required, on any network: it
-is an extra lock on top, and it needs HTTPS (or `localhost`).
+when it knows the address and the port. The passkey lock is never required for this computer
+and your own devices: it is an extra lock on top, and it needs HTTPS (or `localhost`). Other
+people's tailnet devices get in only once a passkey is set up (see below).
 
 **Good practices**
 
 - Prefer **Tailscale** (`tailscale serve`): a private HTTPS address, only for your devices.
 - A network you add **without HTTPS** gets no passkey, no installed app and no notifications, and
   any device on that network can control your agents.
-- **Create a passkey** as soon as wherdr is reached over HTTPS.
+- **Passkey** (optional, over HTTPS): an automatic lock on each device, if you want one. Your
+  own devices get in without it.
 
 How a request is judged, before anything else (WebSockets included):
 
@@ -81,6 +103,20 @@ How a request is judged, before anything else (WebSockets included):
     reads that from Tailscale every 10 seconds (the CLI or Tailscale's socket); an
     interface address in that range proves nothing, since a LAN may use it too. When Tailscale is
     stopped, missing or unreadable for 30 seconds, no direct connection counts as tailnet.
+  - <a id="own-devices"></a>*Your own devices only*: a peer counts when Tailscale lists it under
+    the same user as this machine (`UserID`), is not tagged, and is not a node of someone you
+    shared this machine with (`ShareeNode`). Every other peer is refused with HTTP 403 (`network`, `why: foreign`) while
+    no passkey is set up: another user's device in a team tailnet, a machine someone
+    [shared](https://tailscale.com/kb/1084/sharing) with you (it belongs to another user), a
+    device of someone you shared this machine with, a tagged node (tagged devices
+    belong to no user, your own tagged servers included). When the machine running wherdr is
+    itself tagged, its owner is unknown: no peer counts as yours, so only this computer gets in
+    until a passkey is set up. The same rule applies to the client `tailscale serve` names in
+    `X-Forwarded-For`: without a passkey, it must be one of your devices in the latest reading
+    (a device that joined in the last seconds, or any device while Tailscale cannot be read, is
+    refused). The other peers are remembered from the last valid reading, so a failed reading
+    does not let them in. Once a passkey is set up, they are let through to the lock screen and
+    need that passkey like any device.
 - **Proxy headers**, only when the peer is this computer (a proxy on the machine, such as
   `tailscale serve`): every address in `X-Forwarded-For`, `Forwarded`, `X-Real-IP`,
   `CF-Connecting-IP` must be loopback, the tailnet or a trusted range too. They can only refuse
@@ -106,6 +142,13 @@ How a request is judged, before anything else (WebSockets included):
   loopback or this machine's tailnet address as Tailscale reports it, with Tailscale running
   (`HOST=0.0.0.0`, a LAN address), and says how to fix it.
 
+> [!IMPORTANT]
+> <a id="shared-computers"></a>**Every user of this computer counts as this computer.** Loopback
+> connections are not tied to an OS user: on a machine where other people have an account (a
+> shared server, a lab machine), any of them can open `http://127.0.0.1:7683/` and control
+> your agents. wherdr keeps loopback open so you can always reach it on your own machine. On a
+> machine others log in to, the optional passkey locks loopback too.
+
 > [!IMPORTANT]
 > **A relay on this computer counts as this computer.** A reverse proxy or TCP forward you run
 > on the machine (nginx without forwarded headers, `socat`, an SSH tunnel, a tunnel client) opens

package/docs/troubleshooting.md

@@ -20,6 +20,10 @@
 - **HTTP 403 "wherdr only answers this computer and your tailnet"**: the device is on another
   network (Wi-Fi, LAN). Open wherdr through Tailscale, or name that private network in
   `WHERDR_TRUSTED_NETWORKS` ([Network access](security.md#network-access)).
+- **HTTP 403 "This device is not one of the owner's"**: Tailscale lists the device under another
+  user (a team tailnet), as shared in from another tailnet, or as a tagged node. Without a passkey,
+  wherdr only answers your own devices: log that device in to Tailscale with your own account, or
+  set up a passkey ([Your own devices only](security.md#own-devices)).
 - **HTTP 403 "Tailscale Funnel opens wherdr to the Internet"**: turn Funnel off for wherdr’s port (`tailscale funnel status`).
 - **wherdr stops at startup with "Refusing to listen on …"**: `HOST` is not loopback nor this
   machine's tailnet address. Set `HOST=127.0.0.1` and use `tailscale serve`, or see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wherdr",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "license": "MIT",
   "type": "module",
   "description": "Unofficial mobile web client (PWA) to drive the coding agents running in Herdr",