@alphacoder-v0/pi-loops 0.24.0 → 0.24.2

package/CHANGELOG.md

@@ -5,6 +5,142 @@ All notable changes to pi-loops are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.24.2] - 2026-11-11
+
+Fixes from the 0.24.2 milestone and a review of what merged since 0.24.1: a path rule that never
+fired, faster `pi-loops` commands, page edges that showed what nobody could use, and fewer tools
+offered to a sub-agent that could only fail.
+
+### Fixed
+
+- **A path rule with an aside in parentheses is checked by the model.** The path precheck dropped
+  a trailing parenthetical, so `/tmp/a exists (or /tmp/b exists)` waited on `/tmp/a` alone and never
+  fired when only `/tmp/b` appeared. No word list can tell such an aside from a harmless one, so a
+  condition with one is model-checked again, and `new_trigger` asks the model to keep the person's
+  words with nothing added.
+- **Every `pi-loops` command answers in a fraction of a second.** The command line loaded pi's SDK
+  on every call, about a second of each `status`, `stop` and `--help`; it now loads it only for
+  `import`, the one command that needs it. `pi-loops --version` went from about 1.2 s to 0.17 s here
+  (#168).
+- **The page's inbox matches each project once per request.** `GET /inbox` resolved a finding's
+  directory on disk for every finding, in three passes; 2000 findings took about 24 ms a pass.
+  Each distinct directory is now resolved once per request (#169).
+- **Logs name a conversation the way every screen does.** pi-loops' log lines cut a session id to
+  8 characters while the page, the terminal and the CLI show 13, so an id copied from the page was
+  not found in the log (#177).
+- **Starting or resuming a conversation in the page says why, once.** The new session's events
+  arrived before the page moved to its id, so the page read the old id's history (which the server
+  opened in a pi of its own) and reloaded again on each event after, ending on "the session
+  restarted". The page now waits for the answer, moves to the id it names, and reloads once (#198).
+- **A stopped MCP connection pushes nothing more.** A push read from the server just before the
+  connection stopped could still reach the host after it, and its trust check then read a project
+  directory that might be gone (#188).
+- **An upgrade no longer holds a quit, or the page opening, in silence.** `pi-loops` opening the
+  page during an upgrade waited up to 180 s for the older process with nothing said; it now prints
+  `waiting up to 2 min for a turn in the browser page to finish…` when the wait passes 2 s. A pi
+  window that is quitting asks for the upgrade and leaves at once (#165).
+- **Two page edges no longer show something nobody can use.** An unknown conversation address
+  answers with a page and a link back, not JSON. On a page only this machine can reach, Add a
+  device no longer shows a pairing code: it says how to make the page reachable, and retires the
+  code the server made (#157).
+- **A conversation opened in the page loads pi-loops when the launch named its entry file.** A new
+  conversation in a project with no arguments of its own takes the `-e` that loads pi-loops from
+  another page pi. `-e <package>/src/extension-entry.ts` and `--extension=<path>` were not
+  recognised, so that conversation started without pi-loops (#167).
+- **The page token is made once, even by two first starts at once.** Two windows that started
+  pi-loops together could each write a token, and one then exited. The token and its marker are
+  now written under a lock. A `web-token.v024` that is a symlink is refused before the token is
+  touched; before, it changed the token on every start and then failed (#144).
+- **A loop's finding can no longer pass for an undelivered prompt.** A prompt that never reached its
+  conversation was told from a loop's finding by its text alone, so a loop that wrote
+  `could not be delivered (…): <text>` had its text carried out on Yes. The engine now marks a dead
+  letter with `"undelivered": true`, and only that field changes what a claim asks (#143).
+- **A `$HOME` reached through a symlink is never one project.** Before, a session started in such a
+  `$HOME` lent its trust to loop runs in every project under it, and the create tools accepted any
+  directory under it as the session's own (#142).
+- **Watch for… knows more time words.** "review deps quarterly", "check CI this afternoon",
+  "at nine", "in a few minutes", "next week", "biweekly" and "今晚" were told they read like
+  something to do now, and nothing was set up. They are now watches. A word that only starts like a
+  weekday or a time word ("montage", "sunset", "everyone") no longer reads as one (#146).
+- **`pi-loops --tui --loops-dir <dir>` uses that directory.** The terminal's extension now gets it
+  as `PI_LOOPS_DIR`; before, it used the default. `--open` goes to pi like any flag pi-loops does
+  not read, and `--port`, `--host` and `--allow-host` with `--tui` are dropped, not passed to pi as
+  the 0.24.0 notes said (#145).
+- **`pi-loops --version` prints the pi-loops version,** not pi's. `pi-loops --tui -- --version` asks pi
+  (#148).
+
+### Changed
+
+- **The Loops pane says each thing once.** A named loop shows no prompt peek (the body has the
+  prompt), a failing loop no `quiet ×N` under its error, and the open row no id or cwd. Common cron
+  schedules read in words (`daily 09:00`, `weekdays 18:30`, `weekly Mon 09:00`, `every hour`). A
+  rule row is titled by its condition. The activity strip's "in chat" follows where a run's card
+  went: the conversation that asked for the run, not the one that made its loop (#154).
+- **The page header and composer say less.** The header's clear button did what + New does in
+  this project, so it is gone (`/clear` and `/new` still work). The page says "conversation" where
+  it said "session". The cost badge appears once there is a cost. The composer says "Message pi".
+  The theme button's name is its visible state (#156).
+- **`cron_remove` asks once.** It had a `confirm` parameter: the model asked the person in chat,
+  then the dialog asked again. The parameter is gone, and one call asks through the dialog.
+- **A sub-agent is not offered `new_trigger`, `remove_trigger` or `cron_remove`.** Every call of
+  each was denied at hop 1, so the tools only invited a failed first try (#159, #212).
+- **The agent is told more of what it can use.** `cron_create`'s schedule names `hourly`, `daily`
+  (09:00), `weekly` (Monday 09:00) and that `@daily` is midnight. SKILL.md names the inbox
+  commands a shell can run. The `catch_up` and `spec` descriptions are shorter (#160).
+
+## [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
@@ -337,9 +345,8 @@ unambiguous prefix of it, or the `--name` you gave it — and `/crontab` and `/l
 
 Tools for the model: `cron_create`, `cron_list`, `cron_remove`, `set_cron_job_state`,
 `new_trigger`, `list_triggers`, `remove_trigger`, `set_trigger_state`, plus every tool of every
-configured MCP server. Five of them stop and ask you: creating or removing a trigger, removing a
-cron job — `cron_remove` twice over, a preview the model must show you before the approval itself —
-and any state change that turns automation *on*, or touches another project's. They are the
+configured MCP server. Five of them stop and ask you, once each: creating or removing a trigger,
+removing a cron job, and any state change that turns automation *on*, or touches another project's. They are the
 operations that decide what runs while nobody is watching.
 
 ## Documentation

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
@@ -283,7 +355,7 @@ The rest of the command line does not need a pi session and has no build step; i
 packages the way pi-loops does. `PI_LOOPS_DIR` selects the loops directory, as everywhere.
 
 ```
-pi-loops sessions [--all] [--limit <n>]
+pi-loops sessions [--all] [--limit <n>] [--cwd <dir>]
 pi-loops inspect <file>
 pi-loops export [--session <id>] [--cwd <dir>] [--output <file>] [--exclude-triggers]
 pi-loops import <file> [--cwd <dir>] [--activate-triggers=off|ask|on]
@@ -293,7 +365,9 @@ pi-loops inbox list [--all] [--cwd <dir>] | claim <id> | dismiss <id> [--reason
 ```
 
 `-h` or `--help` anywhere in a subcommand's arguments before a `--` prints that subcommand's usage
-and exits 0 without doing anything else; `pi-loops -h` is `pi-loops --help`. After `--` they are pi's.
+and exits 0 without doing anything else; `pi-loops -h`, `pi-loops help` and `pi-loops --help` are the same. After `--` they are pi's.
+`pi-loops --version` (or `-v`) alone prints the pi-loops version, such as `pi-loops v0.24.2`;
+`pi-loops --tui -- --version` prints pi's.
 A command typed wrong, such as a missing archive path, a flag the command does not read
 (`status does not take --json`) or a word it does not read (`export: unexpected argument "out.pisession"`),
 prints `pi-loops: <what is wrong>` and that command's usage, and exits 2. Any other error prints only its line and exits 1. An unknown command
@@ -306,7 +380,7 @@ in the session's control-plane audit.
 
 ## sessions, inspect
 
-`sessions` lists this project's sessions newest first, one line each: the first sixteen
+`sessions` lists this project's sessions (`--cwd <dir>` names another project) newest first, one line each: the first sixteen
 characters of the id, when the session started, the automation it
 has (`[2 cron, 1 trigger]`, or `[automation off]` when all of it is disabled), and what was first
 said in it — the session's name if it was given one, otherwise the first message, cut at eighty
@@ -350,7 +424,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.2 · 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
@@ -375,7 +449,9 @@ start` starts it now, even with nothing to run yet. `pi-loops restart` stops it,
 process has exited (SIGKILL after 180 seconds), and starts it. A restart, and an upgrade that a pi
 window with a newer pi-loops asks for, first wait up to two minutes for a turn in the browser page to
 finish, so a conversation open there is not cut off mid-answer; a restart first prints `waiting up
-to 2 min for a turn in the browser page to finish…`. A plain `pi-loops stop` ends it at once, and one
+to 2 min for a turn in the browser page to finish…`, and `pi-loops` opening the page prints the same
+line when the older process has not left after 2 seconds. A pi window that is quitting asks for the
+upgrade and does not wait: the next window or `pi-loops` starts the new version. A plain `pi-loops stop` ends it at once, and one
 run during that wait ends the wait. A restart or an upgrade asked for while it already waits is
 answered `already leaving` and does not start the wait again. With `--help`, each of these prints its
 usage and does nothing else.

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 |
@@ -30,7 +30,7 @@ Everything lives under `~/.pi/agent/loops/` (override: `PI_LOOPS_DIR`).
 | `*.lock` | short-lived locks around writes |
 | `polls.json` | last dynamic check per project (shared with 0.22 windows during an upgrade, so a project is not checked twice in one interval) |
 | `dedup.json` | machine-wide trigger dedup window (5 minutes) |
-| `web-token` | the browser page's token, mode 0600. It lives in a file rather than being made per start so the address stays the same one and a signed-in device stays signed in across restarts and upgrades. Delete it and run `pi-loops restart` to sign every device out. The first 0.24 start replaces a token from an earlier version once, and writes `web-token.v024` beside it to record that; a token you write into `web-token` after that is kept |
+| `web-token` | the browser page's token, mode 0600. It lives in a file rather than being made per start so the address stays the same one and a signed-in device stays signed in across restarts and upgrades. Delete it and run `pi-loops restart` to sign every device out. The first 0.24 start replaces a token from an earlier version once, and writes `web-token.v024` beside it to record that; a token you write into `web-token` after that is kept. A `web-token.v024` that is not a regular file (a symlink, even a dangling one) stops pi-loops from starting, as a `web-token` symlink does |
 
 Project-level: `<project>/.pi/mcp.toml` (trusted projects only) and `<project>/.pi/hooks.toml`
 (when allowed).

package/docs/design.md

@@ -153,8 +153,9 @@ machine. Everything here follows from that, and each one has a price.
     three is recorded in the control-plane audit, the self-removals included.
 
 12. **Cycle suppression by hop count.** Sub-agents run at hop 1 and keep the cron and trigger tools
-    (`cron_create`, `cron_remove`, listing, disabling), so a loop can manage automation; the
-    operations that would need a human's yes are denied there, and sub-sessions never run the
+    (`cron_create`, listing, disabling), so a loop can manage automation; the tools whose every
+    call needs a human's yes are not offered there, the other operations that need one are
+    denied, and sub-sessions never run the
     trigger runtime, so nothing nests.
 
 13. **Stdio MCP servers reconnect** with backoff (20 attempts by default), each distinct error
@@ -236,11 +237,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/triggers.md

@@ -54,6 +54,8 @@ noun only when a space sets it apart from the path: `~/备份文件 存在` wait
 `once`, `当`, `如果` or `一旦` and an optional trailing `的时候`, `时` or `后`. `~` and `$HOME` are
 resolved in the process that creates the rule, so they are your home even when pi-loops in the
 background was started with another one; a relative path is resolved against the rule's project.
+An aside in parentheses is a second clause: `/tmp/a exists (or /tmp/b exists)` is true while
+`/tmp/a` is absent, so a condition with one is checked by the model.
 
 Anything else is refused as path-only and checked by the model, as before: a glob, a second clause
 (`~/x appears and it contains ERROR`, `~/a exists or ~/b exists`), another verb, a bare word with no
@@ -138,7 +140,7 @@ that instant (someone wrote it in the last two minutes), the row waits and pi-lo
 later tick. A row whose delivery fails waits a minute, then five, and blocks nothing behind it; at
 the third failure, or when the conversation's file is gone, it is a dead letter: a finding in the
 inbox marked for the conversation, then a `request` audit row (`dead`), then the row is removed, in
-that order so a crash in between loses nothing. A rule's result has its finding already (every match is one), so its dead letter files no second one; any other row's finding reads `could not be delivered (<why>): <prompt>`. A rule with no
+that order so a crash in between loses nothing. A rule's result has its finding already (every match is one), so its dead letter files no second one; any other row's finding reads `could not be delivered (<why>): <prompt>` and carries `"undelivered": true`. Only that field makes a claim carry the prompt out; a loop's finding in the same words is claimed as a finding. A rule with no
 creating conversation (made from a shell, imported, or made by a loop's run) sends results to the
 project's open window as above, and to the inbox (`redirected`, which finds the match's finding and adds nothing) when none is open. One check evaluates every
 rule of the project at once, so it runs under **one** model: the first rule that has one recorded
@@ -207,12 +209,14 @@ poll interval is unaffected: the next scheduled check happens when it would have
 
 ## Cycle safety
 
-Cycles are bounded by a hop count: sub-agents run at hop 1 and still have the
-cron/trigger tools, so a trigger action can schedule a job; they never run the trigger runtime, so
-nothing nests. Prompt-class operations — creating or removing a trigger,
-re-enabling a trigger or a cron job — are denied fail-closed in sub-agents (no control-plane
-prompt channel there). `cron_create` works there, and so does disabling a job of the sub-agent's own
-project; the control-plane audit records `actor: sub-agent`. `cron_remove`, re-enabling a job and
+Cycles are bounded by a hop count: sub-agents run at hop 1 and still have
+`cron_create`, `cron_list`, `set_cron_job_state`, `list_triggers` and `set_trigger_state`, so a
+trigger action can schedule a job; they never run the trigger runtime, so nothing nests.
+`new_trigger`, `remove_trigger` and `cron_remove` are not offered at hop 1: every call of each
+needs a person, and a sub-agent has nobody to ask. The other
+prompt-class operations — re-enabling a trigger or a cron job — are denied fail-closed in
+sub-agents (no control-plane prompt channel there). `cron_create` works there, and so does disabling a job of the sub-agent's own
+project; the control-plane audit records `actor: sub-agent`. Re-enabling a job and
 touching another project's job are denied there like the other prompt-class operations. Sub-agents never handle triggers themselves: they ignore MCP pushes, and the
 runtime audits anything reaching hop ≥ 1 as `cycle_suppressed` (hops are counted per trace, but the
 bound that matters is structural: a sub-agent session never acts on a trigger at all).