@alphacoder-v0/pi-loops 0.24.0 → 0.24.1

package/CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to pi-loops are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.24.1] - 2026-11-10
+
+Two first-run fixes: the `pi-loops` command exists after the first pi session with no question, and
+the first browser gets into the page from one link on every platform, WSL included.
+
+### Changed
+
+- **The first pi session after `pi install` puts `pi-loops` on your `PATH` without asking.** It
+  used to ask in a confirm dialog first. Now it writes the launcher into the first of
+  `~/.local/bin` and `/usr/local/bin` that is on your `PATH`, the way pi's own installer links
+  `pi`, and says so in one line: `[pi-loops] added pi-loops to ~/.local/bin; /pi-loops
+  uninstall-launcher removes it`. It writes only where nothing named `pi-loops` is there, and a
+  checkout never writes one. A link, even one that points nowhere, a directory, or a file it cannot
+  read counts as something there, and the file is created only if it does not exist, so the write
+  never goes through a link at that name or replaces a file; the directory itself may be a link to
+  a directory. A `pi-loops` counts as one that pi-loops wrote only when its first two lines are the
+  ones pi-loops writes, so `uninstall-launcher` never removes a script that only quotes them. It
+  writes only into a directory that is already there, and never makes `~/.local/bin`;
+  `install-launcher`, run by hand, still makes it. When the write fails, one warning line says why,
+  no half-written file is left, and no later session tries that directory again (#180).
+
+  Upgrade note: if you said no to the dialog before, that answer still holds and nothing is
+  written. If you never answered it, the next session writes the launcher.
+
+### Fixed
+
+- `pi-loops install-launcher --dir`, and `/pi-loops install-launcher --dir`, with no directory after
+  `--dir` is a usage error (exit 2). It used to write into the default directory, as if no `--dir`
+  had been given. `uninstall-launcher` reads `--dir` the same way.
+- The first page visit works on every platform. On WSL the browser never opened, the terminal said
+  it had, and the printed address had no key, so Windows Chrome met a door that asked for a code
+  nobody could find. `pi-loops` now prints one link with a one-use key, opens the browser with a
+  per-platform opener (`rundll32.exe`, then `cmd.exe`, on WSL), and says `opened in your browser`
+  only once a browser has spent the key, because `rundll32` exits 0 even when nothing opened. When
+  the opener ran but no browser spent the key within 8 s, it says to open the link if no browser
+  opened. Otherwise, and on WSL when the loops directory's path holds a character Windows cannot
+  name, it says it could not open a browser and that the link works once, for 10 minutes (#179).
+- The door names the ways in that a first browser can take: `pi-loops open` on this machine, and
+  `pi-loops pair` for another device.
+
+### Added
+
+- `pi-loops uninstall-launcher [--dir <dir>]` and `/pi-loops uninstall-launcher` remove the
+  launcher when pi-loops wrote it, and leave any other file named `pi-loops` as it is. No later
+  session writes the launcher again until `install-launcher` puts it back (#180).
+- `pi-loops open [--loops-dir <dir>]` prints a fresh link that signs a browser in, for the
+  project's newest conversation, and opens the browser on it. With no terminal it still prints the
+  link with its key, and opens no browser.
+- `/pi-loops web` opens the conversation you are in from inside pi (a new one in the project before
+  its first answer or under `--no-session`) and copies the link to the clipboard. It says
+  `copied to the clipboard` only when a clipboard command took the link. It needs no `pi-loops` on
+  your PATH.
+
 ## [0.24.0] - 2026-11-09
 
 ### Upgrade notes

package/README.md

@@ -46,11 +46,11 @@ one run with `pi -e .`, which installs nothing. Keep one copy, not two: two copi
 same tools, and pi refuses to load the second — `Tool "cron_create" conflicts with …`, and it
 exits.
 
-Then restart pi, and that is the whole install: `/cron`, `/inbox`, `/triggers` and `/goal` are
-registered by the extension itself, so they work with nothing on your `PATH` and no launcher. The
-`pi-loops` command is a separate thing, needed only for the browser window and the shell
-subcommands — [The browser window, and the command line](#the-browser-window-and-the-command-line)
-sets it up when you want it. The package also ships a skill (`skills/pi-loops`), so the agent knows
+Then start `pi` once, and that is the whole install. That first session puts the `pi-loops` command
+on your `PATH` and says so in one line, so from then on `pi-loops` works from any shell (see
+[The browser window, and the command line](#the-browser-window-and-the-command-line)). `/cron`,
+`/inbox`, `/triggers` and `/goal` are registered by the extension itself, so they work with or
+without that command. The package also ships a skill (`skills/pi-loops`), so the agent knows
 when to reach for `cron_create`, `new_trigger` and the inbox on its own.
 
 ## Your first loop
@@ -178,24 +178,29 @@ you run `pi-loops start --foreground` from your own systemd unit ([docs/cli.md](
 ## The browser window, and the command line
 
 `pi-loops` is the part that needs a launcher: `pi install` puts the package under pi's managed
-directory rather than on your `PATH`, so the command does not exist yet. You are not asked to fix
-that by hand — the first pi session after `pi install` offers to put `pi-loops` on your `PATH`, and
-keeps that launcher working afterwards if pi ever moves the package. Say no and nothing is written,
-and you are not asked again; `/pi-loops install-launcher` writes one whenever you change your mind:
+directory rather than on your `PATH`. You do not fix that by hand. The first interactive pi session
+after `pi install` writes `pi-loops` into the first of `~/.local/bin` and `/usr/local/bin` that is
+already on your `PATH`, says so in one line, and keeps that launcher working afterwards if pi ever
+moves the package:
 
 ```text
-/pi-loops install-launcher            # from inside pi, where the extension is already loaded
+[pi-loops] added pi-loops to ~/.local/bin; /pi-loops uninstall-launcher removes it
+```
+
+It never replaces a `pi-loops` it did not write. When neither directory is on your `PATH`, or on a
+machine where pi itself is never opened, write it yourself and pass `--dir <dir>` to say where:
+
+```text
+/pi-loops install-launcher --dir ~/bin   # from inside pi, where the extension is already loaded
 ```
 
 ```bash
-# or from a shell, on a machine where pi is never opened — the same command, by absolute path
+# or from a shell — the same command, by absolute path
 cd ~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops    # installed from npm
 cd ~/.pi/agent/git/github.com/alphacoder-v0/pi-loops       # installed from GitHub
-node src/cli-entry.mjs install-launcher
+node src/cli-entry.mjs install-launcher --dir ~/bin
 ```
 
-Any of them writes a launcher into the first of `~/.local/bin` and `/usr/local/bin` that is already
-on your `PATH`, and refuses rather than guessing if neither is — pass `--dir <dir>` to say where.
 After that, `pi-loops` works from anywhere:
 
 ```bash
@@ -227,8 +232,14 @@ deletes anything; the session you leave is a file that `resume` lists.
 The page is served by pi-loops in the background on **`http://127.0.0.1:4173/`**, so `pi-loops`
 opens it and exits, and the page stays open when that terminal closes. Its token lives in a file, so
 the address is the same one tomorrow and is worth bookmarking (`[page] port` in `config.toml` moves
-it if 4173 is spoken for). The first visit leaves a cookie and you never see the token again. There
-is no way to drop the token: the page is always on, so it is always behind it.
+it if 4173 is spoken for). `pi-loops` prints one link with a one-use key and opens your browser on
+it, on macOS, Windows, WSL and Linux; when no browser opens, paste that link. The first visit leaves
+a cookie and you never see the token again. There is no way to drop the token: the page is always
+on, so it is always behind it.
+
+A browser that shows "This browser has not been here before." needs a fresh link: run
+`pi-loops open` in a terminal, or `/pi-loops web` inside pi, which also copies the link to the
+clipboard and needs no `pi-loops` on your PATH.
 
 From a phone, the best route is `tailscale serve --bg 4173`: this server stays on loopback and the
 tailnet does TLS and identity. On the same wifi, `[page] host = "0.0.0.0"` in `config.toml` works
@@ -258,22 +269,18 @@ says what is in each one.
 
 ### Uninstall
 
-Stop pi-loops before removing the extension. It keeps running in the background after the extension
-is removed, and nothing else stops it:
+Stop pi-loops and remove the `pi-loops` launcher before removing the extension. pi-loops keeps
+running in the background after the extension is removed, and nothing else stops it; the launcher
+needs the package to run. `uninstall-launcher` removes only a launcher that pi-loops wrote:
 
 ```bash
 pi-loops stop
+pi-loops uninstall-launcher                       # add --dir <dir> if install-launcher --dir <dir> wrote it
 pi remove npm:@alphacoder-v0/pi-loops             # or git:github.com/alphacoder-v0/pi-loops, or the checkout path — whatever you installed
 ```
 
-State stays in `~/.pi/agent/loops` until you delete it. The `pi-loops` launcher stays too. No
-command removes it, so delete the file `install-launcher` wrote:
-
-```bash
-rm ~/.local/bin/pi-loops          # or /usr/local/bin/pi-loops, if ~/.local/bin was not on your PATH
-```
-
-If you gave `install-launcher --dir <dir>`, the launcher is `<dir>/pi-loops`.
+State stays in `~/.pi/agent/loops` until you delete it. After a reinstall, `/pi-loops install-launcher`
+in pi puts the command back, because a removed launcher is not written again by itself.
 
 To go back to 0.22.8, stop pi-loops while this version is still installed, then install 0.22.8:
 
@@ -325,7 +332,8 @@ pi-loops stays stopped until `pi-loops start`, or until `pi-loops` opens the bro
 | `/session-export [path]`, `/session-import <path>` | Portable `.pisession` archive: transcript + jobs + rules + loop state (in the browser front end, `/session export` and `/session import` too; `/sessions` lists) |
 | `/session-share [--public]` | Upload a redacted transcript as a GitHub gist via `gh`, after showing you what it contains. (pi has its own `/share`, which sends the raw session elsewhere first — see [docs/session-archive.md](docs/session-archive.md)) |
 | `/recipe [list\|show\|add\|update\|remove <name>]` | Install a packaged way of running this project on loops — the issue tracker as a state machine, or one research experiment per run — with one question and one confirmation ([docs/recipes.md](docs/recipes.md)) |
-| `/pi-loops [install-launcher]` | Version and paths; `install-launcher` puts the `pi-loops` command on your `PATH` |
+| `/pi-loops web` | Open this conversation in the browser page, and copy its one-use link |
+| `/pi-loops [install-launcher \| uninstall-launcher]` | Version and paths; `install-launcher` puts the `pi-loops` command on your `PATH`, `uninstall-launcher` removes it |
 
 A schedule is a 5-field cron expression, or one of `hourly` / `daily` / `weekly` (also `每天`), or
 `every 30m`, `in 10m`, `at <ISO>`. The `@hourly` / `@daily` / `@weekly` / `@monthly` spellings work

package/README.zh-CN.md

@@ -51,7 +51,7 @@ pi install npm:@alphacoder-v0/pi-loops
 
 重启 pi，装到这里就够了——那四个斜杠命令现在就能用。下面这段只跟 `pi-loops` 这个命令有关：浏览器窗口和几个 shell 子命令靠它，不要浏览器窗口可以先跳过。
 
-`pi install` 把包放在 pi 自己的托管目录里、**不进 `PATH`**，所以此刻 `pi-loops` 这个命令还不存在。这一步不用你自己动手：`pi install` 之后的第一个 pi 会话会问你要不要把 `pi-loops` 放进 `PATH`，写下之后也一直替你维护着——包被 pi 挪到另一个位置，下一个会话会把启动器改回能用的样子，并用一行告诉你改了什么。答 no 就什么都不写，也不会再问第二次；改了主意，`/pi-loops install-launcher` 随时给你写一个：
+`pi install` 把包放在 pi 自己的托管目录里、**不进 `PATH`**，所以此刻 `pi-loops` 这个命令还不存在。这一步不用你自己动手：`pi install` 之后第一次打开 pi，它会直接把 `pi-loops` 放进 `PATH` 上已有的目录，并用一行告诉你放在哪、怎么删；之后也一直替你维护着——包被 pi 挪到另一个位置，下一个会话会把启动器改回能用的样子，并用一行告诉你改了什么。不想要的话，`pi-loops uninstall-launcher` 删掉它，以后也不会再写；改了主意，`/pi-loops install-launcher` 随时给你写一个：
 
 ```text
 /pi-loops install-launcher                         # 在 pi 里面，扩展本来就加载着
@@ -162,17 +162,18 @@ pi-loops upgrade --check                           # 只看看有没有新的
 
 ## 卸载
 
-卸载扩展前先停止 pi-loops：
+卸载扩展前先停止 pi-loops，并删掉 `pi-loops` 启动器（`uninstall-launcher` 只删 pi-loops 自己写的那个）：
 
 ```bash
 pi-loops stop
+pi-loops uninstall-launcher
 pi remove npm:@alphacoder-v0/pi-loops              # 当初怎么装的就怎么删：npm: 包名、git: ref 或检出路径
 pi remove git:github.com/alphacoder-v0/pi-loops
 pi -e /path/to/pi-loops                            # 或者：只在这次启动试用，什么都不装
 pi update --extensions                             # 对齐已安装的包
 ```
 
-数据留在 `~/.pi/agent/loops`，想清就删目录。
+数据留在 `~/.pi/agent/loops`，想清就删目录。以后重新安装时，在 pi 里运行 `/pi-loops install-launcher` 把命令放回来：删掉的启动器不会再自动写回。
 
 要退回 0.22.8：趁 0.23 还装着，先停止 pi-loops，再安装 0.22.8：
 

package/docs/cli.md

@@ -18,31 +18,68 @@ pi-loops --model anthropic/claude-opus-5 -e .   # anything it does not recognise
 ```
 
 The page is served by pi-loops in the background, not by this command. `pi-loops` starts pi-loops
-in the background if it is not running, asks it to open the conversation, opens your browser and
-exits:
+in the background if it is not running, asks it to open the conversation, prints a link, opens your
+browser and exits:
 
 ```
 $ pi-loops
 started pi-loops in the background
-pi-loops page: http://127.0.0.1:4173/c/424aba43-…/ (opened in your browser)
-  if it did not open, or from another browser: http://127.0.0.1:4173/c/424aba43-…/?open=c0ff… (works once, for 10 minutes)
+pi-loops: http://127.0.0.1:4173/c/424aba43-…/?open=c0ff…
+  opened in your browser
 ```
 
-The first line appears only when this command started pi-loops. The browser is opened on a file
-that only you can read, under the loops directory's `pages/open/`, which sends it to the
-conversation with a one-use key; the key is in no command line, and the file is removed once the
-browser has used it, or after a minute. "Opened in your browser" means an opener started; it cannot
-tell whether the browser could read the file. A browser confined by snap or flatpak (Ubuntu's
-default Firefox is one) cannot read a hidden directory such as `~/.pi`, so it shows an error
-instead: use the address on the next line. That address, printed only on a terminal, holds a second
-one-use key that works for 10 minutes, never the token, because what a terminal prints stays in its
-scrollback. Over ssh, with `--no-open`, or with no terminal, nothing is opened, no file is written,
-and the line ends `(open it in a browser)`. A conversation the page already has open is not started
-again, so pi arguments given for it are not applied, and the last line says which:
+The first line appears only when this command started pi-loops. The link holds a one-use key that
+works for 10 minutes, never the token, because what a terminal prints stays in its scrollback. It is
+printed before the browser is tried, so a browser on this machine that did not open gets in with a
+paste. The last line says what happened:
+
+- `  opened in your browser`: a browser loaded the page and spent the launch key within 8 s,
+  watched while the opener runs. The opener is `open` on macOS,
+  `rundll32 url.dll,FileProtocolHandler` on Windows, `rundll32.exe url.dll,FileProtocolHandler` on
+  WSL (`WSL_DISTRO_NAME` set, or a kernel release that names Microsoft; then `cmd.exe /c start`
+  when `rundll32.exe` cannot start), and `xdg-open` on other Linux, which gets 10 s because it takes
+  about 5 s to give up when there is no browser. An opener's exit code is not enough: `rundll32`
+  exits 0 for a target it cannot open.
+- `  if no browser opened, open the link above (it works once, for 10 minutes)`: the opener ran, but
+  no browser spent the key within 8 s.
+- `  could not open a browser here; open the link above (it works once, for 10 minutes)`: every
+  opener failed, or Linux has no `DISPLAY` or `WAYLAND_DISPLAY`.
+- `  open the link above in a browser on this machine`: over ssh or mosh, where nothing is opened.
+- `  open the link above in a browser (it works once, for 10 minutes)`: with `--no-open`.
+
+The browser is opened on a file that only you can read, under the loops directory's `pages/open/`,
+which sends it to the conversation with a second one-use key; that key is in no command line, and
+the file is removed once the browser has used it, or after a minute. On WSL the Windows browser
+reads that file as `file://wsl.localhost/<distro>/…`, which it cannot do when the loops directory's
+path holds a character Windows does not allow in a name (`\ : * ? " < > |`); then the last line says
+it could not open a browser. A browser confined by snap or flatpak
+(Ubuntu's default Firefox is one) cannot read a hidden directory such as `~/.pi`, so it shows an
+error instead: use the printed link. With no terminal (stdout piped or redirected), no key is
+printed, because a file would keep it: the link is the page's address, and the next line is
+`  pi-loops open prints a link that signs a browser in`. A conversation the page already has open
+is not started again, so pi arguments given for it are not applied, and the last line says which:
 `  this conversation was already open; --model was not applied`. Opening can wait up to 15 s for
 an older pi in that conversation to stop; after 3 s the command says
 `waiting for pi-loops to open the conversation…` on stderr, and it waits up to 30 s in all.
 
+### A fresh link: `pi-loops open` and `/pi-loops web`
+
+```
+pi-loops open [--cwd <dir>] [--loops-dir <dir>]
+```
+
+opens the page on the project's newest conversation (a new one when the project has none), with
+the same output as `pi-loops`, except that it prints the link with its key with no terminal too,
+because that link is what it is for; it opens no browser then. `--loops-dir` names the loops
+directory, as it does for `pi-loops` and as `PI_LOOPS_DIR` does. Run it when a browser shows the door ("This browser has not been
+here before."), or when the printed link has been used or is older than 10 minutes. Inside pi,
+`/pi-loops web` does the same for the conversation you are in (a new one in the project when pi
+has saved nothing of it yet, before its first answer or under `--no-session`), shows the same
+lines, and copies the link to the clipboard (on WSL, the Windows clipboard). It adds
+`  copied to the clipboard` only when `pbcopy`, `clip`, `clip.exe`, `wl-copy`, `xclip` or `xsel`
+said it took the link; a copy through the terminal (OSC 52), which no terminal confirms, is tried
+without a line. It needs no `pi-loops` on your PATH.
+
 Both windows are complete pi sessions: each conversation in the page is a `pi --mode rpc` that
 pi-loops runs for it, so the session file, your models, tools and extensions are the same either
 way. What the browser cannot do is pi's own built-in slash commands, which do not exist in that
@@ -219,16 +256,49 @@ by the id in its header.
 
 `pi install` puts this package under pi's managed directory rather than on your `PATH`, so the
 command that is meant to start your sessions is at first reachable only by absolute path. The
-extension does that step for you: the first pi session that finds no `pi-loops` anywhere on your
-`PATH` asks once whether to write one, and a no is remembered — nothing is written and you are not
-asked again. Afterwards it keeps that launcher current: if the copy it runs is not there any more
+extension does that step for you, with no question: the first interactive pi session after
+`pi install` writes `pi-loops` into the first of `~/.local/bin` and `/usr/local/bin` that is on your
+`PATH`, and says so in one line:
+
+```text
+[pi-loops] added pi-loops to ~/.local/bin; /pi-loops uninstall-launcher removes it
+```
+
+It writes only where nothing named `pi-loops` is there yet. A link, even one that points nowhere, a
+directory, or a file it cannot read counts as something there, and the file is created only if it
+does not exist, so the write never goes through a link at that name. The directory itself may be a
+link to a directory, as a dotfiles `~/.local/bin` often is. A `pi-loops` this project did not write,
+such as your own wrapper, is left alone, and so is one that runs another copy of this package still
+on disk, which is that copy's to keep. With neither directory on your `PATH`, or with
+the one on your `PATH` not made yet, nothing is written and nothing is said: a session start never
+makes a directory. When the write fails, for example because `/usr/local/bin` belongs
+to root, one warning line says why, and no later session tries that directory again; a `PATH` that
+names another directory is a new try. A checkout never writes a launcher that is not there.
+
+Afterwards the extension keeps that launcher current: if the copy it runs is not there any more
 (pi installed the package by the other route), or that copy is the one now running and the node has
-changed, the next session rewrites it and says so in one line. A `pi-loops` this project did not
-write — your own wrapper — is left alone, and so is one that runs another copy of this package still
-on disk, which is that copy's to keep. A checkout is never asked to write a launcher that is not
-there, though one written from a checkout is still kept working.
+changed, the next session rewrites it and says so in one line.
 
-To write one yourself, or after a no, run it from inside pi, where the extension is already loaded:
+To remove it, and stop every later session from writing it again:
+
+```text
+/pi-loops uninstall-launcher
+```
+
+```bash
+pi-loops uninstall-launcher
+pi-loops uninstall-launcher --dir ~/bin
+```
+
+`--dir` needs a directory after it, here and on `install-launcher`: a `--dir` with nothing after it,
+or with a flag after it, is a usage error (exit 2), not the default directory.
+
+It removes only a launcher of ours that this copy keeps. For any other file named `pi-loops` it
+says whose file it is, leaves it as it is, and exits 1. Either way it remembers the choice in
+`ui.json`.
+
+To write one yourself, after `uninstall-launcher` or into another directory, run it from inside pi,
+where the extension is already loaded:
 
 ```text
 /pi-loops install-launcher
@@ -243,6 +313,8 @@ node src/cli-entry.mjs install-launcher
 node src/cli-entry.mjs install-launcher --dir ~/bin
 ```
 
+`install-launcher` clears the choice `uninstall-launcher` remembered.
+
 It writes a small `sh` script that names the node you ran it with and the package it lives in — a
 launcher rather than a symlink. Neither path is trusted for ever: if the package is not where it
 was, the launcher looks in both of the directories above (the ones pi installs into, under the agent
@@ -350,7 +422,7 @@ spellings `pi-loops host status|abort|stop|start` and `/cron host` still work.
 $ pi-loops status
 pi-loops
   pid 2949521 on box, started 2026-09-09 13:33, model openai-codex/gpt-5.5
-  pi-loops 0.24.0 · 1/1 loops, 0/0 rules enabled · inbox: 0 new
+  pi-loops 0.24.1 · 1/1 loops, 0/0 rules enabled · inbox: 0 new
   started by the shell that ran pi-loops
   conversation 424aba43-0c1f "fix the flaky login test" open in pid 939915 (tui)
   running nightly (run-97ffb250) since 2026-09-09 13:34: check the repo issues

package/docs/configuration.md

@@ -8,7 +8,7 @@ Everything lives under `~/.pi/agent/loops/` (override: `PI_LOOPS_DIR`).
 | `logs/pi-<pid>.log` | what each pi process diagnosed: jobs disabled, writes that failed, sub-agent warnings. Rotated at 2 MB, newest 5 processes kept |
 | `mcp.toml` | MCP servers — see [mcp.md](mcp.md) |
 | `hooks.toml` | lifecycle hooks — see [hooks.md](hooks.md) |
-| `ui.json` | preferences that outlive a session: `panel` (written by `/cron panel on\|off`); `model` / `thinking` — the last ones you chose in the browser page, applied to the next session that does not say otherwise; `host` (`"stopped"` after a manual stop); `launcher` (your answer to the launcher offer); `heldJobsNotice` (the one-time notice about plain jobs of closed conversations); `lastPage` (the conversation `GET /` opens) |
+| `ui.json` | preferences that outlive a session: `panel` (written by `/cron panel on\|off`); `model` / `thinking` — the last ones you chose in the browser page, applied to the next session that does not say otherwise; `host` (`"stopped"` after a manual stop); `launcher` (`"declined"` after `uninstall-launcher`, so the launcher is not written again; `"failed"`, with `launcherFailedIn`, the directory a write failed in, so it is retried only when that changes); `heldJobsNotice` (the one-time notice about plain jobs of closed conversations); `lastPage` (the conversation `GET /` opens) |
 | `jobs.json`, `triggers.json` | cron jobs and trigger rules (machine-global, each with a `cwd`) |
 | `jobs.json.bak` | the last `jobs.json` that read cleanly, kept so a damaged store can be restored |
 | `state/<id>.md` | loop notes; plain Markdown, editable |

package/docs/design.md

@@ -236,11 +236,15 @@ machine. Everything here follows from that, and each one has a price.
     the copy it names is this one and the node or the shape of the script has changed. Either way
     one line says that it was rewritten and why. One naming another copy that is still there is that
     copy's to keep current, so an install and a checkout both being opened never trade the file back
-    and forth. With no launcher anywhere, the question `install-launcher` already asks is asked once,
-    and a no is remembered in `ui.json` and never asked again; `/pi-loops install-launcher` still
-    writes one whenever you want it, and clears that mark. A `pi-loops` carrying no marker of ours
-    is somebody's own wrapper and is left alone, and a checkout is never asked for one that is not
-    there — nobody ran `pi install`. The decision is `launcherState` / `refreshLauncher` in
+    and forth. With no launcher anywhere, the first interactive session writes one into a directory
+    already on the PATH without asking, and says so in one line with the command that removes it,
+    because a confirm dialog and a second start cost more than the file does (0.24.1, #180).
+    `uninstall-launcher` removes only a launcher of ours and records `declined` in `ui.json`, so it
+    is not written again; `/pi-loops install-launcher` still writes one whenever you want it, and
+    clears that mark. A write that failed is recorded with its directory and not retried until the
+    target changes. A `pi-loops` carrying no marker of ours is somebody's own wrapper and is left
+    alone, and a checkout is never given one that is not there — nobody ran `pi install`. The
+    decision is `launcherAction`, `launcherState` and `refreshLauncher` in
     [../src/cli.ts](../src/cli.ts), beside the one function that renders the script, so it is
     testable without pi; the extension is the caller.
 

package/docs/troubleshooting.md

@@ -43,8 +43,10 @@ longer loaded.
 
 **The browser window says "This browser has not been here before."** It has no cookie for this
 address, which is normal for a new device, a new browser, a private window, or after clearing site
-data. Press **add device** in a browser that is already signed in and scan the QR, or type the six
-digits into the box on that page. The terminal that started the session printed a code too.
+data. On this machine, run `pi-loops open` in a terminal (or `/pi-loops web` inside pi) for a link
+that signs this browser in. For another device, run `pi-loops pair`, or press **add device** in a
+browser that is already signed in and scan the QR, then type the six digits into the box on that
+page.
 
 **The phone cannot reach it at all.** The server binds loopback by default, and a phone has no
 route to that. Either `tailscale serve --bg 4173` (the server stays on loopback; the tailnet does

package/docs/web-ui-parity.md

@@ -969,6 +969,17 @@ weaker, and worth converting whenever one of them breaks.
       otherwise reloading a bookmark with a stale code on it burns the budget the phone needs.
       `test/web.test.ts`: *a signed-in browser reloading a stale pairing code does not spend a
       guess*.
+- [x] The first browser on this machine gets in with one action. `pi-loops` prints one link with a
+      one-use key and opens the browser on it, or says it could not, so a paste of that link works
+      on the first try; on WSL the Windows browser is opened through `rundll32.exe`, then
+      `cmd.exe`, and "opened" is said only once a browser has spent the key. `pi-loops open` prints a fresh link, and the door names it.
+      `test/browser-open.test.ts`: *opened means the opener exited with a success code or is still
+      running*. `test/cli.test.ts`: *what pi-loops prints once the page has the conversation*,
+      *pi-loops open is a word of its own*. `test/web-page.test.ts`: *the door is a heading, one
+      line per way in, and the code field*.
+- [x] `/pi-loops web` opens the conversation you are in from inside pi, with no `pi-loops` on your
+      PATH: the same link and opener, and the link copied to the clipboard. Checked by reading
+      (`src/pi-loops.ts` cannot be imported by a test).
 - [x] Pairing survives an upgrade: the token and the paired devices are files outside the package,
       so a device stays signed in across restarts and new versions. A browser paired before 0.24.0
       pairs once more, because its cookie held the token, which no cookie may hold now.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",

package/src/browser-open.ts

@@ -0,0 +1,169 @@
+/**
+ * Which command opens a browser here, and whether one did. The table copies pi's own opener (macOS
+ * `open`, Windows `rundll32`) and adds the WSL branch pi lacks: there `xdg-open` finds no browser and
+ * exits 3 after five seconds, so the Windows side is asked directly, with pi's Windows opener. "Opened" comes from the exit
+ * code, never from the spawn alone: a terminal that says it opened a browser when nothing opened
+ * leaves a person waiting for a window that never comes.
+ */
+
+import { spawn } from "node:child_process";
+import * as os from "node:os";
+import { pathToFileURL } from "node:url";
+
+/**
+ * One command to try: what to run, from where, which exit codes mean the browser got it, and how
+ * long it may run before still running counts as opened.
+ */
+export type Opener = { cmd: string; args: string[]; cwd?: string; okExit: number[]; waitMs: number };
+
+/** For an opener that exits as soon as it has handed the address on. */
+const QUICK_MS = 1_500;
+/** xdg-open that finds no browser exits 3 after about five seconds. */
+const XDG_OPEN_MS = 10_000;
+
+/** What the choice depends on, passed in so a test can be any machine. */
+export type OpenEnv = { platform: NodeJS.Platform; release: string; env: NodeJS.ProcessEnv };
+
+/** ssh and mosh set at least one of these; opening a browser on the far end helps nobody. */
+export function isRemoteTty(env: NodeJS.ProcessEnv = process.env): boolean {
+	return ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY", "MOSH_CONNECTION"].some((k) => !!env[k]);
+}
+
+function isWsl(e: Pick<OpenEnv, "platform" | "release" | "env">): boolean {
+	return e.platform === "linux" && (!!e.env.WSL_DISTRO_NAME || /microsoft/i.test(e.release));
+}
+
+/** The commands to try in order, or why none is tried. */
+export function openerFor(e: OpenEnv & { target: string }): Opener[] | "no-display" | "remote" {
+	if (isRemoteTty(e.env)) return "remote";
+	const t = e.target;
+	if (e.platform === "darwin") return [{ cmd: "open", args: [t], okExit: [0], waitMs: QUICK_MS }];
+	// No shell: cmd would read `&` in the address as the end of the command.
+	if (e.platform === "win32") return [{ cmd: "rundll32", args: ["url.dll,FileProtocolHandler", t], okExit: [0], waitMs: QUICK_MS }];
+	// Both start from a Windows drive: a long \\wsl.localhost cwd breaks them. Not wslview: wslu 3.2.3
+	// reads a wsl.localhost address as a relative Linux path and exits 0 without opening anything. Not
+	// explorer.exe: it exits 1 whether or not anything opened. rundll32 exits 0 even for a missing
+	// file, so cmd.exe is reached only when rundll32.exe cannot start.
+	if (isWsl(e))
+		return [
+			{ cmd: "rundll32.exe", args: ["url.dll,FileProtocolHandler", t], cwd: "/mnt/c", okExit: [0], waitMs: QUICK_MS },
+			// cmd re-reads its line: `^` escapes the characters it would act on.
+			{ cmd: "cmd.exe", args: ["/c", "start", "", t.replace(/[\^&|]/g, "^$&")], cwd: "/mnt/c", okExit: [0], waitMs: QUICK_MS },
+		];
+	if (!e.env.DISPLAY && !e.env.WAYLAND_DISPLAY) return "no-display";
+	return [{ cmd: "xdg-open", args: [t], okExit: [0], waitMs: XDG_OPEN_MS }];
+}
+
+/**
+ * The address the opener is given for the launch file, which holds the one-use key so no argv does.
+ * On WSL the browser is a Windows one, which reads the file through `\\wsl.localhost`: measured on
+ * WSL 2 with rundll32 and `cmd.exe /c start`, each loads the file and follows it to the page.
+ * Undefined on WSL without `WSL_DISTRO_NAME`, which that address needs, and for a path holding a
+ * character Windows does not allow in a name: `\\wsl.localhost` shows those under other names, so
+ * the browser cannot find the file while rundll32 still exits 0.
+ */
+export function openFileTarget(file: string, e: Pick<OpenEnv, "platform" | "release" | "env">): string | undefined {
+	const href = pathToFileURL(file).href;
+	if (!isWsl(e)) return href;
+	const distro = e.env.WSL_DISTRO_NAME;
+	return distro && !/[\\:*?"<>|]/.test(file) ? `file://wsl.localhost/${encodeURIComponent(distro)}${href.slice("file://".length)}` : undefined;
+}
+
+/** This machine, as `openerFor` reads it. */
+export function thisMachine(): OpenEnv {
+	return { platform: process.platform, release: os.release(), env: process.env };
+}
+
+/**
+ * Hand `target` to each opener in turn until one takes it: true when one exits with a code it
+ * counts as success, or is still running at its own deadline, which is how a browser started
+ * straight from the opener looks. `waitMs` replaces every deadline, for a test.
+ */
+export async function openUrl(target: string, e: OpenEnv = thisMachine(), waitMs?: number): Promise<boolean> {
+	const openers = openerFor({ ...e, target });
+	if (typeof openers === "string") return false;
+	for (const opener of openers) if (await tryOpener(opener, e.env, waitMs ?? opener.waitMs)) return true;
+	return false;
+}
+
+function tryOpener(o: Opener, env: NodeJS.ProcessEnv, waitMs: number): Promise<boolean> {
+	return new Promise((resolve) => {
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(o.cmd, o.args, { stdio: "ignore", detached: true, cwd: o.cwd, env });
+		} catch {
+			resolve(false); // the next opener, or the printed link
+			return;
+		}
+		const timer = setTimeout(() => {
+			child.unref();
+			resolve(true);
+		}, waitMs);
+		child.once("error", () => {
+			clearTimeout(timer);
+			resolve(false);
+		});
+		child.once("exit", (code) => {
+			clearTimeout(timer);
+			resolve(code !== null && o.okExit.includes(code));
+		});
+	});
+}
+
+/** One command that copies its stdin to the clipboard and exits 0 when it has. */
+export type CopyCommand = { cmd: string; args: string[]; cwd?: string };
+
+/**
+ * The clipboard commands to try in order, the ones pi's `copyToClipboard` runs. Not OSC 52, which
+ * pi also writes and which no terminal confirms: tmux in Windows Terminal drops it, so a terminal
+ * that said "copied" after it could be wrong. None over ssh or mosh, where this machine's clipboard
+ * is not the one in front of you.
+ */
+export function copyCommandsFor(e: OpenEnv): CopyCommand[] {
+	if (isRemoteTty(e.env)) return [];
+	if (e.platform === "darwin") return [{ cmd: "pbcopy", args: [] }];
+	if (e.platform === "win32") return [{ cmd: "clip", args: [] }];
+	if (e.platform !== "linux") return [];
+	// The link is ASCII, so clip.exe reading it in the console code page changes nothing.
+	const windows = isWsl(e) ? [{ cmd: "clip.exe", args: [], cwd: "/mnt/c" }] : [];
+	return [
+		...windows,
+		...(e.env.WAYLAND_DISPLAY ? [{ cmd: "wl-copy", args: [] }] : []),
+		...(e.env.DISPLAY ? [{ cmd: "xclip", args: ["-selection", "clipboard"] }, { cmd: "xsel", args: ["--clipboard", "--input"] }] : []),
+	];
+}
+
+/** Copy `text` with the first command that takes it: true only when one exited 0. */
+export async function copyText(text: string, e: OpenEnv = thisMachine()): Promise<boolean> {
+	for (const c of copyCommandsFor(e)) if (await runCopy(c, text, e.env)) return true;
+	return false;
+}
+
+const COPY_WAIT_MS = 5_000;
+
+function runCopy(c: CopyCommand, text: string, env: NodeJS.ProcessEnv): Promise<boolean> {
+	return new Promise((resolve) => {
+		let child: ReturnType<typeof spawn>;
+		try {
+			// xclip and xsel stay behind to own the selection; "exit" is the command that answered.
+			child = spawn(c.cmd, c.args, { stdio: ["pipe", "ignore", "ignore"], cwd: c.cwd, env });
+		} catch {
+			resolve(false); // the next command
+			return;
+		}
+		const timer = setTimeout(() => {
+			child.kill();
+			resolve(false);
+		}, COPY_WAIT_MS);
+		child.once("error", () => {
+			clearTimeout(timer);
+			resolve(false);
+		});
+		child.once("exit", (code) => {
+			clearTimeout(timer);
+			resolve(code === 0);
+		});
+		child.stdin?.once("error", () => {}); // EPIPE from a command that exited first: its exit code decides
+		child.stdin?.end(text);
+	});
+}