wherdr 1.3.0 → 1.3.2

package/README.md

@@ -9,18 +9,28 @@ computer and on your phone.</b></p>
 
 <p align="center"><a href="https://wherdr.dev"><b>wherdr.dev</b></a> · <code>curl -fsSL https://wherdr.dev/install | sh</code> · <code>herdr plugin install afloury/wherdr</code></p>
 
+<p align="center"><a href="https://wherdr.dev/demo/"><b>Try it in your browser — no install</b></a>: the real app on scripted agents, nothing runs.</p>
+
 <p align="center"><a href="https://github.com/afloury/wherdr/actions/workflows/ci.yml"><img src="https://github.com/afloury/wherdr/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a></p>
 
 ## Quick start
 
-With [Herdr](https://herdr.dev) running and Node.js 22 (or Bun), on macOS or Linux:
+On the computer that runs [Herdr](https://herdr.dev) (≥ 0.9.1), macOS or Linux, one command:
 
 ```sh
-npx wherdr          # or: bunx wherdr, pnpm dlx wherdr — then open http://localhost:7683
+curl -fsSL https://wherdr.dev/install | sh
 ```
 
-To keep it: `npm install -g wherdr`, then `wherdr service install` starts it at every login, and
-`wherdr phone` walks you through phone access. See [the `wherdr` command](#the-wherdr-command).
+It installs the wherdr [Herdr plugin](#install-as-a-herdr-plugin), starts wherdr on
+`http://localhost:7683` and opens its setup guide in your browser; then **prefix+i** in Herdr opens
+the wherdr panel. Without Herdr, it says where to get it; on a Mac without Node.js 22, it offers
+`brew install node`; on Linux, Docker works too. On a server without a screen (or over SSH), it
+prints the address and the phone steps instead. See [The one command](#the-one-command).
+
+Other ways, after it: `herdr plugin install afloury/wherdr` (the same plugin, without the
+checks), `npx wherdr` (or `bunx wherdr`, `pnpm dlx wherdr`; see
+[the `wherdr` command](#the-wherdr-command)), `brew install afloury/tap/wherdr`, or
+[Docker by hand](#recommended-always-on-server--tailscale).
 
 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
@@ -28,6 +38,13 @@ saved on the server (`data/onboarding.json`), so your other devices do not show
 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:
+`localhost` stays valid on the computer. The installer, the Herdr plugin and `wherdr open` open
+that address too when it is already published.
+
 wherdr is a small self-hosted web app that talks to the Herdr server on your machine. **On a
 computer**, it can replace the Herdr terminal client day to day: your spaces, tabs and split panes
 side by side, live conversations and real terminals, drag-and-drop layout, keyboard shortcuts
@@ -61,21 +78,40 @@ it on `localhost`, or from your other devices over Tailscale.
 *Unofficial project. Not affiliated with or endorsed by Herdr, Anthropic or OpenAI. Claude,
 Claude Code, Codex and other product names are trademarks of their respective owners.*
 
+## Why wherdr
+
+- **Herdr's splits, live.** A tab with several panes is drawn in Herdr's real layout, every pane
+  live; drag a pane to move it or a divider to resize, and the change goes to Herdr itself.
+- **A passkey lock.** Face ID, Touch ID, Windows Hello or Android unlock the app; once a passkey
+  exists, nothing about your agents is served to a locked session.
+- **The agent's diff.** Git status and diff of each agent's working folder, one click away from
+  its conversation.
+- **The herdr-projects board.** A coordinator and its threads grouped under their project, with
+  the project's task lists as a live board and one-click replies.
+- **Keyboard and global search.** One shortcut searches every agent and conversation; next
+  agent, new tab, pane swaps and `1`–`9` answers never need the mouse.
+- **Real time, and private.** The real terminal over a WebSocket, a push when an agent needs
+  you, and your phone through Tailscale: nothing is on the Internet.
+
+Details in [Features](#features) and [Security](#security).
+
 ## Contents
 
 - [Quick start](#quick-start)
+- [Why wherdr](#why-wherdr)
 - [Features](#features)
 - [How it works](#how-it-works)
 - [Requirements](#requirements)
-- [Installation](#installation): [which setup?](#which-setup) ·
+- [Installation](#installation): [the one command](#the-one-command) ·
+  [which setup?](#which-setup) ·
   [always-on server + Tailscale](#recommended-always-on-server--tailscale) ·
   [other private networks](#other-private-networks) ·
   [the `wherdr` command](#the-wherdr-command) ·
-  [one computer, no Docker](#simple-one-computer-no-docker) ·
+  [from source](#from-source-no-docker) ·
   [as a Herdr plugin](#install-as-a-herdr-plugin) ·
   [Docker on a Mac: Reveal/Open](#wherdr-in-docker-on-a-mac-reveal-in-finder-open-and-modalto)
 - [Updating](#updating)
-- [Install the app on your phone](#install-the-app-on-your-phone)
+- [Install it as an app](#install-it-as-an-app)
 - [Configuration](#configuration)
 - [Several machines (SSH)](#several-machines-ssh)
 - [Claude and Codex quotas](#claude-and-codex-quotas)
@@ -99,7 +135,10 @@ Claude Code, Codex and other product names are trademarks of their respective ow
   A command the agent proposes (shell code block, or inline `! command`) can be copied without
   its prompt, or run in the agent's shell mode (`!`, Claude Code, Codex and omp) after you
   confirm the full command.
-- **Terminal view**: the real terminal (xterm.js, WebGL or DOM renderer) with take-over. On a
+- **Terminal view**: the real terminal (xterm.js, WebGL or DOM renderer) with take-over. Opening
+  it resizes the real pane to your screen; closing it gives the pane the size it had before
+  (after 30 seconds when the connection just dropped, e.g. a locked phone), unless a Herdr
+  client attached meanwhile laid it out its own way. On a
   computer, drag over the text on screen to select it: releasing the button copies it, as do
   `⌘C` / `Ctrl+Shift+C`. The history is browsed with the wheel, not by dragging past the edge.
   Links (OSC 8 hyperlinks and plain `http(s)://` URLs, even wrapped over several rows) open in a
@@ -110,7 +149,9 @@ Claude Code, Codex and other product names are trademarks of their respective ow
 - **Composer**: send messages while the agent works (queued, cancellable), attach or paste
   photos and the files the agent can read (Claude Code: PDFs, notebooks, text and code of any
   extension; Codex: notebooks, text and code), run slash commands (`/compact`, `/clear`, `/context`, `/usage`…) and see the output
-  of local commands. Stop button while the agent works.
+  of local commands. Stop button while the agent works. A long pasted text (log, output) becomes
+  a "Pasted text · N lines" card, sent to the agent as it is and shown the same way in the
+  conversation, where it opens in full with Copy; long typed messages fold with Show more.
 - **Codex updates and limits**: in a Codex conversation, a new Codex version shows above the
   field with an **Update** button (runs Codex's official update command on that machine, after
   confirmation), then **Restart to update** on the same conversation. When wherdr cannot run it
@@ -211,16 +252,64 @@ Web Push, lock) runs in Nitro.
 
 ## Installation
 
+### The one command
+
+On the computer that runs Herdr, as your user, on macOS or Linux:
+
+```sh
+curl -fsSL https://wherdr.dev/install | sh
+```
+
+The script ([read it first](https://wherdr.dev/install), source in
+[`website/public/install`](website/public/install)) never uses sudo. It:
+
+1. checks **Herdr ≥ 0.9.1**; without it, it stops with the link to [herdr.dev](https://herdr.dev);
+2. leaves alone a wherdr that **already answers** on the port: a Herdr plugin install is offered
+   its update, a Docker install shows its update command, anything else is left as it is. A
+   `wherdr` container managed from another folder is never replaced or stopped;
+3. checks what wherdr runs on: Docker Compose v2 on Linux when your user can use it, otherwise
+   **Node.js 22** or Bun (always on macOS). On a Mac without them, it offers
+   `brew install node` when Homebrew is there; elsewhere it stops with the install links;
+4. runs `herdr plugin install afloury/wherdr --yes`: the [Herdr plugin](#install-as-a-herdr-plugin)
+   installs wherdr in `~/wherdr`, starts it on `http://localhost:7683`, starts it again with Herdr,
+   opens the setup guide in your browser (first install) and binds **prefix+i** to its panel;
+5. on a computer **without a screen** (no `DISPLAY` on Linux, or an SSH session): opens nothing,
+   prints the local address, an `ssh -L` tunnel to reach it from your computer, and the phone
+   steps (`wherdr phone`: Tailscale state, the address, the QR code once it answers). With
+   Docker, it offers to run `tailscale serve` for you (asked first), and wherdr enables the
+   published address by itself: no browser is needed on the server. Run the command again at
+   any time to check the phone address.
+
+Settings, as environment variables (`curl -fsSL https://wherdr.dev/install | WHERDR_PORT=7684 sh`):
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `WHERDR_DIR` | `~/wherdr` | Install folder (plugin settings, data, log). |
+| `WHERDR_PORT` | `7683` | Local port. |
+| `WHERDR_MODE` | — | `native`: Node.js even when Docker is there. `docker`: no plugin, Docker Compose by hand in `WHERDR_DIR` (Linux; see below). |
+| `WHERDR_YES` | — | `1` answers yes to every question (non-interactive use). |
+| `WHERDR_NO_BROWSER` | — | `1` never opens a browser. |
+| `WHERDR_REF` | latest | Git tag or branch of the plugin (or of `docker-compose.yml` with `WHERDR_MODE=docker`). |
+| `WHERDR_PLUGIN` | `afloury/wherdr` | A local checkout to link and build instead (development, tests). |
+
+**Docker by hand, with the script:** `curl -fsSL https://wherdr.dev/install | WHERDR_MODE=docker sh`
+writes `docker-compose.yml` and `.env` to `~/wherdr`, creates the bind-mount folders, pulls the
+published image and starts it, without the plugin; it asks before replacing a file it did not
+create. The same steps by hand are in the next section.
+
+Update: run the command again (it offers the update), or **U** in the wherdr panel.
+
 ### Which setup?
 
-| | **Always-on server + Tailscale** (recommended) | **One computer, no Docker** |
+| | **Always-on server + Tailscale** (recommended) | **One computer** |
 | --- | --- | --- |
-| Runs on | A machine that never sleeps: Raspberry Pi, mini-PC, home server, private VPS (Linux, Docker) | The computer you work on (macOS or Linux, Node.js 22) |
+| Runs on | A machine that never sleeps: Raspberry Pi, mini-PC, home server, private VPS (Linux) | The computer you work on (macOS or Linux) |
 | Reach it from | Your phone and every computer on your tailnet | That computer only (`http://localhost:7683`) |
 | Installable app, push notifications, passkeys | Yes (private HTTPS from `tailscale serve`) | Desktop browser only; no phone access |
 | Other machines (a Mac, a laptop…) | Added in Herdr over SSH, shown in wherdr | Also possible, but they are only reachable while this computer is awake |
 
-Both setups use the same app. You can start with the second one and move to the first later.
+Both use [the one command](#the-one-command) and the same app. You can start with the second one
+and move to the first later.
 
 ### Recommended: always-on server + Tailscale
 
@@ -231,7 +320,9 @@ wherdr stays on your private network: it is **never published on the Internet**.
 (`herdr` or `herdr server`), with the integrations of the agents you use
 (`herdr integration install claude|codex`).
 
-**2. wherdr with Docker** (Linux, Compose v2):
+**2. wherdr.** Run [the one command](#the-one-command) on the server (over SSH, it prints the
+address and the phone steps instead of opening a browser), then go to step 3. Or set up Docker
+Compose by hand (Linux, Compose v2), as follows:
 
 ```sh
 git clone https://github.com/afloury/wherdr.git
@@ -246,7 +337,7 @@ Edit `.env` (every value has a default; `HOST_HOME` defaults to your `$HOME`):
 | `HOST_HOME` | `/home/alice` | Your home folder on the server (default: `$HOME`). Mounted at the same path, read-only. |
 | `PUID` / `PGID` | `1000` | Your user and group IDs (`id -u`, `id -g`). |
 | `PORT` | `7683` | Listening port, published on `127.0.0.1` only. |
-| `APP_URL` | `https://server.example.ts.net:7683/` | Private HTTPS address of the app (step 3; also used as the Web Push contact and an allowed host). Use `http://localhost:7683/` for local testing. |
+| `APP_URL` | `http://localhost:7683/` | Leave it with Tailscale: wherdr adopts the address of step 3 by itself. Set a private HTTPS address only for [another private network](#other-private-networks) (Web Push contact and allowed host; it then always wins). |
 | `HOST_LABEL` | `server` | Name of this machine in the app. |
 | `TZ` | `Europe/Paris` | Time zone for timestamps and logs. |
 | `WHERDR_UPDATE_CHECK` | `off` | Disable the daily check for a new release (default `on`). |
@@ -284,11 +375,38 @@ 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. Then open
-**Settings › Phone** in wherdr on the server (`http://localhost:7683/#/settings?section=phone`),
-paste that address: wherdr checks it answers, sets it as `APP_URL` (saved in `data/app-url.json`;
-an HTTPS `APP_URL` in `.env` wins) and shows its QR code. Without Docker, the same page publishes
-wherdr itself: one button, asked first.
+forwards to wherdr's local HTTP port. Only devices of your tailnet can reach it.
+
+**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`
+publishes on this machine and adopts the HTTPS address that points to its own port (allowed
+host and `APP_URL`, saved in `data/app-url.json`; an HTTPS `APP_URL` in `.env` wins). An address
+removed from `tailscale serve` is refused again. Nothing a request says can enable an address:
+only Tailscale's own state on the machine does, and an address that `tailscale funnel` opens to
+the Internet is never adopted. Without Docker, wherdr runs the `tailscale` command; in Docker
+it reads Tailscale's socket, mounted by `docker-compose.yml` (`/var/run/tailscale`). After
+Tailscale itself restarts (an update), restart the container.
+
+What that mount gives: Tailscale's local API, with the rights of the host user the container
+runs as. Anyone may read it; if that user is Tailscale's operator
+(`tailscale set --operator=$USER`), the API also accepts changes from it (serve, funnel…), and
+`:ro` on the folder does not prevent that. wherdr itself only sends `GET` requests. This is not
+a new privilege: the container already drives Herdr, which is a shell of that same user. To do
+without it, remove the line from `docker-compose.yml`: wherdr then no longer finds the address
+by itself, and the one command (or the plugin's phone step) run after `tailscale serve` hands
+it over.
+
+**Settings › Phone** on the server (`http://localhost:7683/#/settings?section=phone`) shows the
+state and the QR code; without Docker it also publishes wherdr itself: one button, asked first.
+From a terminal, `wherdr phone` (npm, Homebrew) or the [one command](#the-one-command) run again
+(Docker, Herdr plugin) checks the same thing, and
+`curl -fsS http://127.0.0.1:7683/api/phone` prints the state as JSON. A container started from
+an older `docker-compose.yml` has no Tailscale socket: paste the address in Settings › Phone,
+or run the one command again, which sends it.
+
+If the phone shows **"This address isn't enabled yet"** (403), the address it opened is not one
+`tailscale serve` publishes for wherdr's port on that machine: the page gives the command to run
+there.
 
 **Why HTTPS matters.** Browsers only allow three things on `https://` (or on `localhost` itself):
 
@@ -296,7 +414,7 @@ wherdr itself: one button, asked first.
 - **push notifications** (on iOS, only in the installed app);
 - **passkeys** for the lock screen (Face ID, Touch ID, Windows Hello, Android).
 
-**4. On the phone:** open the address, [install the app](#install-the-app-on-your-phone), then
+**4. On the phone:** open the address, [install the app](#install-it-as-an-app), then
 Settings → **Enable notifications**. **On the computer:** use the same address in a browser; the
 desktop layout can replace the Herdr terminal client for daily work.
 
@@ -328,8 +446,8 @@ works with any private network that gives it an **HTTPS address with a valid cer
 - **`APP_URL` set to that address** (`.env` with Docker, or the environment of `wherdr` /
   `npm start`), then restart wherdr. Its hostname is allowed automatically and it enables Web
   Push. Add `HERDR_WEB_ALLOWED_HOSTS` only if you also open wherdr under another name. The
-  one-click address check in **Settings › Phone** only knows `*.ts.net` addresses; an HTTPS
-  `APP_URL` in the environment always wins.
+  automatic adoption and the address check in **Settings › Phone** only know the `*.ts.net`
+  addresses of `tailscale serve`; an HTTPS `APP_URL` in the environment always wins.
 - **Never exposed without authentication.** wherdr keeps listening on `127.0.0.1`; only the
   proxy listens on the private network. Turn on the passkey lock as soon as another device can
   reach it.
@@ -408,8 +526,8 @@ wherdr phone                # phone state, the app's phone setup page, QR code o
 | `wherdr start` · `stop` · `restart` | Background server, pid and log in `~/wherdr`. `start` says *started* only once the port answers; otherwise it prints the end of the log. With a login service installed, they drive the service. |
 | `wherdr status` | Address, process, service, data folder and log. |
 | `wherdr logs` (`-f` to follow, `-n 100`) | The log, `~/wherdr/wherdr.log`. |
-| `wherdr open` | Opens wherdr in the browser. |
-| `wherdr phone` | Whether your phone can reach wherdr (Tailscale, `tailscale serve`, the address answering), the link to **Settings › Phone** where you publish it in one click, and the QR code once the address answers. |
+| `wherdr open` | Opens wherdr in the browser: its tailnet address when published and answering, else `localhost`. |
+| `wherdr phone` | Whether your phone can reach wherdr (Tailscale, `tailscale serve`, the address answering), the `tailscale serve` command to publish it when it is not (wherdr then enables the address by itself), the link to **Settings › Phone**, and the QR code once the address answers. |
 | `wherdr service install` · `uninstall` | Start at login: a LaunchAgent on macOS (`~/Library/LaunchAgents/dev.wherdr.plist`), a `systemd --user` unit on Linux (`loginctl enable-linger` keeps it running while you are logged out). |
 | `wherdr doctor` | Checks Node/Bun, Herdr and its socket, the port, the service, the data folder and `APP_URL`. |
 
@@ -421,6 +539,18 @@ plugin and the install script use), `--session` (a named Herdr session). Every
 environment, then that file. `start` and `service install` remember the port and folders for
 the other commands.
 
+**Homebrew:** `brew install afloury/tap/wherdr` installs the same package; the first install also
+brings Homebrew's Node.js (heavier than the Herdr plugin when Node.js 22 is already there). Then:
+
+1. `brew services start wherdr`: runs `wherdr run` now and at every login, log in
+   `$(brew --prefix)/var/log/wherdr.log` (`wherdr logs` reads it).
+2. `wherdr open`: the setup guide in your browser.
+3. Its Phone step (or `wherdr phone`).
+
+On a Homebrew install, `wherdr start`, `stop`, `restart` and `service install` point to
+`brew services` (the installed path changes at each upgrade); `wherdr status` and `wherdr doctor`
+show the Homebrew service. Update: `brew upgrade wherdr && brew services restart wherdr`.
+
 The login service records the **absolute path** of the runtime (n, nvm, fnm, Volta or Homebrew
 node), since launchd and systemd do not see your shell's `PATH`. It refuses to point at a
 temporary `npx` / `pnpm dlx` / `bunx` folder: install the package globally first. To update:
@@ -430,10 +560,11 @@ Bun runs wherdr too (WebSockets, push, passkeys and Herdr's socket work); when N
 also installed, `bunx wherdr` hands the server to Node, the reference runtime. Set
 `WHERDR_RUNTIME=bun` to keep Bun.
 
-### Simple: one computer, no Docker
+### From source, no Docker
 
-The quickest way to try it, and the way to run wherdr **on macOS**: Docker Desktop cannot reach
-Herdr's Unix socket on the host. With Herdr running, Git and Node.js 22 on the same machine:
+For development, or to run a checkout of your own (Docker Desktop cannot reach Herdr's Unix socket
+on macOS, so wherdr always runs natively there). With Herdr running, Git and Node.js 22 on the
+same machine:
 
 ```sh
 git clone https://github.com/afloury/wherdr.git
@@ -460,12 +591,14 @@ and logs a warning.
 
 ### Install as a Herdr plugin
 
-Herdr can also install wherdr itself, on Linux and macOS, with Herdr ≥ 0.9.1. In three lines:
+This is what [the one command](#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
    (`✓ 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 just prints `http://localhost:7683/#/setup`). Updates open nothing.
+   display; a headless server, or `WHERDR_NO_BROWSER=1` in the environment of the install, just
+   prints `http://localhost:7683/#/setup`). Updates open nothing.
 2. In Herdr, press **prefix+i** (`ctrl+b` then `i` with the default prefix): the **wherdr** panel,
    with the state, **O** Open wherdr and **P** Set up my phone. The install prints the key it
    chose (see [Panel key](#panel-key)).
@@ -479,7 +612,8 @@ the install still succeeds and says why; press **S** in the panel once it is fix
 setup by itself:
 
 - **Docker** on Linux when Docker Compose v2 works for your user: the published image, from
-  `~/wherdr` (`docker-compose.yml`, `.env`), exactly like the [one-line installer](https://wherdr.dev/install).
+  `~/wherdr` (`docker-compose.yml`, `.env`), the same files as `WHERDR_MODE=docker` of
+  [the one command](#the-one-command).
 - **Node.js 22** everywhere else, and always on macOS (Docker Desktop cannot reach Herdr's
   socket): the plugin downloads the prebuilt npm package of its version (or builds wherdr in its
   own folder when that fails), copies it to `~/wherdr/app` and runs it detached from there, with
@@ -522,7 +656,7 @@ Without a key: `herdr plugin action invoke panel --plugin afloury.wherdr`. The p
 | Action | What it does |
 |---|---|
 | `panel` | The **wherdr** panel (a popup) |
-| `open` | Opens wherdr in the browser |
+| `open` | Opens wherdr in the browser (its tailnet address when published and answering) |
 
 Up to 1.2.0 the panel action was called `wherdr`: change a key bound to `afloury.wherdr.wherdr` to
 `afloury.wherdr.panel` (Herdr has no action aliases; the install warns about such a key and
@@ -604,12 +738,32 @@ 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.
 
+**Update in one tap.** When wherdr runs from the Herdr plugin (Node.js mode), a global npm install
+or Homebrew, the banner has an **Update** button instead of the command, for a session opened on
+this computer (`localhost`) or unlocked with a passkey. wherdr installs the new version in a
+process of its own, restarts, and checks that `/api/health` reports the new version within 60
+seconds; the app shows the progress and reloads on the new version. If the new version does not
+answer, wherdr goes back to the previous one by itself (the plugin keeps the previous copy in
+`~/wherdr/app.prev`, npm reinstalls the previous version, Homebrew points back to the previous keg)
+and the app says so. Every step is logged in `~/wherdr/update.log`.
+
+| Setup | What Update does |
+| --- | --- |
+| Herdr plugin, Node.js | Unpacks the npm package of the new version into `~/wherdr/app`, keeps the old copy, restarts |
+| `npm install -g wherdr` | `npm install -g wherdr@X.Y.Z`, then restarts (login service included) |
+| Homebrew | `brew upgrade wherdr`, then `brew services restart wherdr` |
+
+Docker shows the command instead: replacing its own container would need the Docker socket (root
+on the host) inside it. `npx wherdr` runs from a temporary folder: run `npx wherdr@latest` again.
+
 | Setup | Update command (in the wherdr folder) |
 | --- | --- |
 | Docker, published image (default) | `docker compose pull && docker compose up -d` |
 | Docker, built from source | `git pull && docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build` |
-| No Docker | `git pull && npm ci && npm run build`, then restart wherdr |
+| From source | `git pull && npm ci && npm run build`, then restart wherdr |
 | `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` |
+| The one command | Run `curl -fsSL https://wherdr.dev/install \| sh` again: it offers the update |
 | Herdr plugin, Docker | **U** in the **wherdr** panel (pulls the image, restarts the container) |
 | Herdr plugin, Node.js | **U** in the **wherdr** panel, or `herdr plugin install afloury/wherdr --yes` (wherdr restarts on the new version) |
 
@@ -632,16 +786,23 @@ docker run -d --name watchtower --restart unless-stopped \
 
 Pin a version instead of `latest` with `WHERDR_IMAGE=ghcr.io/afloury/wherdr:1.2.0` in `.env`.
 
-## Install the app on your phone
+## Install it as an app
 
-The app must be served over HTTPS (see [Requirements](#requirements)).
+The app must be served over HTTPS (see [Requirements](#requirements)). Installed, wherdr opens
+in its own window, without the browser's bars.
 
 - **iPhone / iPad** (iOS 16.4 or later): open the address in **Safari** → Share →
   **Add to Home Screen**. Open wherdr from the home screen, then Settings → **Enable
   notifications**. On iOS, push notifications only work in the installed app.
 - **Android**: open the address in **Chrome** → menu → **Install app** (or Add to Home
   screen), then Settings → **Enable notifications**.
-- **Computer**: just use the address in a browser; Chrome and Edge can also install it.
+- **Mac, Safari** (macOS 14 Sonoma or later): File → **Add to Dock**.
+- **Chrome, Edge, Brave** (macOS, Windows, Linux): the install icon at the right of the address
+  bar, or menu → **Cast, save and share** → **Install page as app** (Edge: Apps → **Install
+  this site as an app**).
+- **Arc** cannot install web apps
+  ([Arc Help Center](https://resources.arc.net/hc/en-us/articles/25678978728983-Does-Arc-for-Desktop-Support-Progressive-Web-Apps)):
+  open the address in Safari or Chrome for that, or keep wherdr as an Arc favorite.
 
 Then Settings → Security → **Enable passkey lock** on each device.
 
@@ -653,8 +814,9 @@ All settings are environment variables (`.env` with Docker).
 | --- | --- | --- |
 | `PORT` | `7683` | Listening port. |
 | `HOST` | `127.0.0.1` (`npm start`) | Listening address without Docker. Keep it on loopback. |
-| `HOST_LABEL` | server hostname (`wherdr` in Docker) | Name of this machine in the app (can be renamed in the app). |
-| `APP_URL` | *(empty)* | App address and allowed host; a valid HTTPS URL enables Web Push. HTTP, empty or invalid values disable Web Push with a warning. |
+| `HOST_LABEL` | server hostname | Name of this machine in the app (can be renamed in the app). In Docker the installer writes the host's short name; left empty, wherdr shows the name Tailscale gives the machine, else `wherdr`. |
+| `APP_URL` | *(empty)* | App address and allowed host; a valid HTTPS URL enables Web Push. HTTP, empty or invalid values disable Web Push with a warning. With Tailscale, leave it empty: wherdr adopts the address `tailscale serve` publishes. |
+| `TAILNET_REFRESH_MS` | `30000` | How often wherdr reads again what `tailscale serve` publishes for its port. |
 | `HERDR_WEB_ALLOWED_HOSTS` | *(empty)* | Additional hostnames or IP addresses allowed to open the app, comma-separated. |
 | `PASSKEY_USER` | `wherdr` | User name stored with the passkeys. |
 | `DATA_DIR` | `./data` | VAPID keys, push subscriptions, passkeys, recent folders. |
@@ -764,7 +926,7 @@ worktree. It is optional; with it installed, wherdr adds:
   | **To test** | You confirm the work | Confirm, Problem, Question |
   | **To decide** | Only you can unblock it | Question, Answer |
   | **To review** | Pull requests for you | Reviewed, Comment |
-  | **In progress** | What threads are really doing | (live threads) |
+  | **In progress** | What threads are really doing | (live threads) Add info |
   | **In queue** | Decided: the coordinator launches the first one as soon as a thread slot frees | Move up / down, Launch now, Clarify, Remove from queue |
   | **Blocked** | Waiting for someone or something external | Unblock, Clarify |
   | **To do** | To do soon, in your priority order; never launched on its own | Move up / down, Queue it, Launch now, Clarify, Back to backlog |
@@ -775,9 +937,11 @@ worktree. It is optional; with it installed, wherdr adds:
   project may only need Backlog, In progress and Done); any other `##` list shows in a neutral
   style after Backlog. French titles and common synonyms are recognized (À tester, En file,
   À faire, Plus tard…). Every button sends a ready-made message to the coordinator, which edits
-  `TASKS.md` (wherdr never writes it). The In queue header shows the thread slots in use
-  (`max_parallel_threads` in `PROJECT.md`) and the next task, plus the machine's global limit
-  when one is set (`2 of 2 thread slots in use on <machine> (all projects)`).
+  `TASKS.md` (wherdr never writes it). **Add info**, on a working thread, opens a text field:
+  what you type goes to the coordinator, which passes it on to that thread as is. The In queue
+  header shows the thread slots in use (`max_parallel_threads` in `PROJECT.md`) and the next
+  task, plus the machine's global limit when one is set
+  (`2 of 2 thread slots in use on <machine> (all projects)`).
 - **Max threads per machine**, across all projects: herdr-projects only limits threads per
   project, so three coordinators could still start a dozen threads on one small machine. Set a
   limit per machine in **Settings → Plugins → herdr-projects** (empty `—` = no global limit;
@@ -850,7 +1014,10 @@ Actions declared by the plugins installed on a machine (`herdr plugin install|li
 the menus: workspace / tab / pane actions in the agent menu, global actions in the machine menu.
 wherdr always passes the agent's pane explicitly. It asks for confirmation before running an
 action, except for actions that only show or check something (list, show, status, doctor…).
-Actions that open a plugin panel open it in the attached Herdr terminal client, not on the phone.
+Actions that open a plugin pane or popup open it in the attached Herdr terminal client, not on the
+phone: the menu marks them **Opens in Herdr**. wherdr's own plugin actions (its panel, open in the
+browser) are not listed. With a single machine, the machine's actions are in the **…** menu of
+its session row, under the agent list header.
 
 **herdr-projects** actions that ask for input (New project, continue this workspace as a
 project, open, pause, resume) are run by wherdr itself as `herdr-projects` commands, because
@@ -885,7 +1052,9 @@ container talks to the Herdr server running on the host.
   (port forwarding, public reverse proxy, ngrok…); the only exception is a Cloudflare Tunnel
   behind Cloudflare Access, with its risks.
 - Requests are accepted only for `localhost`, loopback addresses, the runtime's hostname, the
-  hostname in `APP_URL`, and the runtime's network interface addresses (those of the container
+  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),
+  and the runtime's network interface addresses (those of the container
   with Docker). Add other private names or IP addresses to `HERDR_WEB_ALLOWED_HOSTS`
   (comma-separated) before using them. An unlisted name returns HTTP 403 (`host` / "Host not
   allowed"); add it to `HERDR_WEB_ALLOWED_HOSTS`, then restart wherdr. This host check also
@@ -933,8 +1102,10 @@ See [SECURITY.md](SECURITY.md) to report a vulnerability.
   (`herdr integration install claude|codex|omp`) and start a new agent.
 - **Passkeys or notifications unavailable**: the page must be served over HTTPS (or
   `localhost`). On iPhone, notifications need the app installed on the home screen.
-- **HTTP 403 when opening the app through another name**: add that private hostname or IP
-  address to `HERDR_WEB_ALLOWED_HOSTS`, or use the hostname in `APP_URL`, then restart wherdr.
+- **HTTP 403 "This address isn't enabled yet"**: for a tailnet address, run the command the
+  page gives on the machine: it tells whether `tailscale serve` publishes wherdr's port there.
+  For another private name, add the hostname or IP address to `HERDR_WEB_ALLOWED_HOSTS`, or use
+  the hostname in `APP_URL`, then restart wherdr.
 - **Remote machine offline**: `docker compose logs | grep machine` shows its state. Test SSH as
   wherdr does, from the container:
   `docker compose exec herdr-web ssh -o BatchMode=yes laptop '~/.local/bin/herdr status server'`.

package/bin/lib/brew.mjs

@@ -0,0 +1,86 @@
+// Homebrew install (the project's tap): the formula's `brew services` entry runs
+// `wherdr run` at login (launchd label sh.brew.wherdr, homebrew.mxcl.wherdr before
+// Homebrew 5; systemd unit of the same name on Linux), with its log in
+// <prefix>/var/log/wherdr.log. The wherdr commands describe and point to it
+// instead of their own pid file and login service.
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { BIN, homebrewInstall } from './core.mjs'
+
+export const BREW_LABELS = ['sh.brew.wherdr', 'homebrew.mxcl.wherdr']
+
+// <prefix>/Cellar/wherdr/<version>/libexec/… → the prefix, its brew and the service log.
+export function brewPaths(bin = BIN) {
+  if (!homebrewInstall(bin)) return null
+  const prefix = bin.slice(0, bin.search(/[\\/]Cellar[\\/]wherdr[\\/]/))
+  return { prefix, brew: path.join(prefix, 'bin', 'brew'), log: path.join(prefix, 'var', 'log', 'wherdr.log') }
+}
+
+// Output of `brew services info wherdr --json` → { loaded, running }; null if unreadable.
+export function parseServiceInfo(text) {
+  try {
+    const info = [].concat(JSON.parse(text)).find(s => s?.name === 'wherdr')
+    return info ? { loaded: !!info.loaded, running: !!info.running } : null
+  } catch { return null }
+}
+
+// `launchctl print gui/<uid>/<label>` → running when it reports "state = running".
+export function parseLaunchctl(text) {
+  return /^\s*state = running\s*$/m.test(text)
+}
+
+const run = (cmd, args, env) => spawnSync(cmd, args, { encoding: 'utf8', timeout: 20_000, env: { ...process.env, ...env } })
+
+// Without a usable brew: the LaunchAgent written by `brew services start`, and launchd's state.
+function launchdState(home) {
+  for (const label of BREW_LABELS) {
+    if (!existsSync(path.join(home, 'Library', 'LaunchAgents', `${label}.plist`))) continue
+    const r = run('launchctl', ['print', `gui/${process.getuid?.() ?? ''}/${label}`])
+    return { loaded: r.status === 0, running: r.status === 0 && parseLaunchctl(r.stdout) }
+  }
+  return { loaded: false, running: false }
+}
+
+// null when this wherdr does not come from Homebrew; otherwise { prefix, brew, log, loaded, running }.
+export function brewService(bin = BIN, home = os.homedir()) {
+  const paths = brewPaths(bin)
+  if (!paths) return null
+  const r = run(paths.brew, ['services', 'info', 'wherdr', '--json'], { HOMEBREW_NO_AUTO_UPDATE: '1', HOMEBREW_NO_ENV_HINTS: '1' })
+  const state = (r.status === 0 && parseServiceInfo(r.stdout))
+    || (process.platform === 'darwin' ? launchdState(home) : { loaded: false, running: false })
+  return { ...paths, ...state }
+}
+
+// ------------------------------------------------- what the commands say
+
+// `wherdr start|stop|restart|service install` on a Homebrew install: the message
+// pointing to brew services, or null to go on (start while the service runs).
+export function brewRedirect(command, brew) {
+  if (!brew) return null
+  if (command === 'start') return brew.running ? null : 'this wherdr was installed with Homebrew: start it (now and at every login) with `brew services start wherdr`.'
+  if (command === 'stop') return brew.running ? 'wherdr runs as a Homebrew service (launchd / systemd restart it): stop it with `brew services stop wherdr`.' : null
+  if (command === 'restart') return 'this wherdr was installed with Homebrew: restart it with `brew services restart wherdr`.'
+  if (command === 'service') return 'this wherdr was installed with Homebrew: start it at login with `brew services start wherdr` (stop: `brew services stop wherdr`).'
+  return null
+}
+
+// Rows of `wherdr status` for a Homebrew install.
+export function brewStatusRows(brew) {
+  return {
+    process: brew.running ? 'Homebrew service (brew services)' : null,
+    service: brew.running ? 'Homebrew (brew services) · running'
+      : brew.loaded ? 'Homebrew (brew services) · started but not running: wherdr logs'
+        : 'Homebrew (brew services) · not started: brew services start wherdr',
+    log: brew.log,
+    hint: '\n  Start it: brew services start wherdr (now and at every login), then wherdr open.',
+  }
+}
+
+// `wherdr doctor` line for a Homebrew install: [level, text], level ok | warn | fail.
+export function brewDoctor(brew) {
+  if (brew.running) return ['ok', `Login service: Homebrew (brew services), running · log ${brew.log}`]
+  if (brew.loaded) return ['fail', `Login service: Homebrew (brew services), started but not running. See wherdr logs (${brew.log}).`]
+  return ['warn', 'Login service: Homebrew (brew services), not started · brew services start wherdr runs wherdr now and at every login.']
+}