@alphacoder-v0/pi-loops 0.22.8 → 0.24.1

package/CONTRACT.md

@@ -37,7 +37,7 @@ talks to it only through a recipe directory, `hooks.toml`, and the `pi-loops inb
 
 ### 2.2 Unit formats
 
-- **Recipe**: `recipe.toml` is TOML. Required: `name` (a lowercase letter, then lowercase letters, digits and hyphens), `summary`, `levels` (non-empty, from the three levels), at least one `[[job]]`. Each `[[job]]` requires `name`, `schedule` (a recurring schedule) and `playbook` (a file in the same directory). Optional keys: `needs_tracker`, `setup`, `files`, `tier`, `useful_when`, `needs`, `needs_propose`, `budget_hint_usd`; per job `verify`, `timeout`, `thinking`, `tools`, `prompt`.
+- **Recipe**: `recipe.toml` is TOML. Required: `name` (a lowercase letter, then lowercase letters, digits and hyphens), `summary`, `levels` (non-empty, from the three levels), at least one `[[job]]`. Each `[[job]]` requires `name`, `schedule` (a recurring schedule) and `playbook` (a file in the same directory). Optional keys: `line`, `needs_tracker`, `setup`, `files`, `tier`, `useful_when`, `needs`, `needs_propose`, `budget_hint_usd`; per job `verify`, `timeout`, `thinking`, `tools`, `prompt`.
 - **Playbook**: Markdown with pi's skill frontmatter (`name`, `description`), one level line, and one `## Never` section.
 - **Finding**: one JSON object with the fields `id`, `created_at` (RFC 3339), `status`, `kind` (`checkpoint` | `news`), `source`, `run_id`, `cwd`, `text`, `verified` (`true` | `false` | `null`), `dismiss_reason` (string | `null`). Fields are only added at the end; none is renamed, removed or changed in type.
 - **Event**: `run_start` and `run_end`. The payload has `run_job` and `run_id`; on `run_end` also `run_ok`, `run_findings`, `run_error`, `run_cost_usd`. Each field also enters the command's environment as `PI_<FIELD IN UPPER CASE>`, unset when the payload has `null`.
@@ -59,7 +59,7 @@ A finding is written only by a run, and its `text` is what the run said. `status
 
 ### 2.6 Deterministic rules
 
-- `kind`: `text` contains `· waits:` (preceded by the start of the text or whitespace, case-insensitive) → `checkpoint`; otherwise `news`.
+- `kind`: a finding filed from a rule result is always `news`; otherwise `text` contains `· waits:` (preceded by the start of the text or whitespace, case-insensitive) → `checkpoint`, else `news`.
 - Level line: the first line that is exactly `Autonomy: <one word>`. When that word is one of the three levels, it is the level; otherwise the playbook has no level.
 - Manifest validity: the required keys and values of 2.2. TOML is parsed as standard TOML.
 
@@ -90,9 +90,9 @@ Three sentences each: what it is, what it depends on, and why the contract does
 - **An install leaves an `.orig/` copy and `.recipe.json` in the project and lists the directory in `.git/info/exclude`.** Depends on the three-way merge of `/recipe update` and on keeping playbooks out of the repository's history. Another merge strategy leaves 2.1 and 2.3 as they are.
 - **The values of `needs` and `needs_propose` are the preflight checks this version performs (`gh`, `git-remote`, `ci-workflows`, `lockfile`, `tracker-github`).** Depends on this version's set of checks. A recipe that names a check this version does not have is refused; that binds the recipe to a version and does not change the contract.
 - **A recipe name is at most 64 characters.** Depends on the install directory name staying readable.
-- **A rule's command times out after 5000 ms, its stdout is cut at 4000 characters, summaries at 2000, and the host drains for 3 seconds before it exits; output goes to `logs/pi-<pid>.log` or `host.log`.** Depends on log rotation. Changing any of these numbers leaves the event fields of 2.2 as they are.
+- **A rule's command times out after 5000 ms, its stdout is cut at 4000 characters, summaries at 2000, and pi-loops drains for 3 seconds before it exits; output goes to `logs/pi-<pid>.log` or `host.log`.** Depends on log rotation. Changing any of these numbers leaves the event fields of 2.2 as they are.
 - **Creating a job needs a pi (interactive, or `pi --mode rpc`).** `pi-loops recipe add` in a terminal only copies files and prints the `/cron add` lines. Depends on the decision that a job belongs to a session. The "create the jobs" of 2.3 is done by `/recipe add` inside pi.
-- **A headless host runs the jobs while no pi is open.** Depends on the process hand-off. Events and findings have the same shape in both processes.
+- **An always-on pi-loops runs every loop and rule check, whether or not a pi is open.** Depends on pi-loops starting on demand, and on the session lease. Events and findings have the same shape in both processes.
 
 ## 4. Not done
 
@@ -108,9 +108,9 @@ Three sentences each: what it is, what it depends on, and why the contract does
 The scripts are in `test/contract/`. `sh test/contract/run.sh` runs all five; each also runs alone.
 
 1. **Second implementation** `test/contract/1-second-implementation.sh`: `test/downstream/closed-loop.sh` (sh and jq install a recipe, let it run, find its finding by `run_id` and claim it, touching no private file), then python3 `tomllib` reads every packaged `recipe.toml` and checks the required keys of 2.2; then every packaged recipe is installed with `pi-loops recipe add` and its files are searched for the names of the loops directory's files. Pass: every step exits 0 and no playbook names a private file. A failure means private state has leaked into the contract, or a recipe depends on it.
-2. **Stopped machine** `test/contract/2-stopped.sh`: with no pi and no host running, write a `hooks.toml` rule, install a directory with `pi-loops recipe add`, and dismiss a finding with `pi-loops inbox dismiss`. Pass: all three succeed. A failure means a write depends on a mechanism.
-3. **Cross-check** `test/contract/3-cross-check.sh`: four rules, each run through two implementations that share nothing, over the same samples; pass when the outputs are equal line for line. TOML: `src/toml.ts` against python3 `tomllib`, over every `recipe.toml` in the repository and `examples/mcp.toml`. `kind`: `src/protocol.ts` against `grep -E`, over every `<inbox>` text the repository has shown. Level line: `src/recipe.ts` against `awk`, over every playbook in `recipes/` and in this repository's `.agents/skills/`. Finding: `pi-loops inbox list --all --json` against `jq` reading the ten fields of 2.2 off each line of `inbox.jsonl` directly. Event: the same loop run once by the host and once by a pi driven over rpc; the two `run_end` payloads have the same fields and the same run values.
-4. **Private state cleared** `test/contract/4-private-state.sh`: after one run, delete everything in the loops directory that 2.1 does not name as instance data and start the host again. Pass: it runs the loop again and the earlier findings are unchanged field for field.
+2. **Stopped machine** `test/contract/2-stopped.sh`: with no pi and pi-loops not running, write a `hooks.toml` rule, install a directory with `pi-loops recipe add`, and dismiss a finding with `pi-loops inbox dismiss`. Pass: all three succeed. A failure means a write depends on a mechanism.
+3. **Cross-check** `test/contract/3-cross-check.sh`: four rules, each run through two implementations that share nothing, over the same samples; pass when the outputs are equal line for line. TOML: `src/toml.ts` against python3 `tomllib`, over every `recipe.toml` in the repository and `examples/mcp.toml`. `kind`: `src/protocol.ts` against `grep -E`, over every `<inbox>` text the repository has shown. Level line: `src/recipe.ts` against `awk`, over every playbook in `recipes/` and in this repository's `.agents/skills/`. Finding: `pi-loops inbox list --all --json` against `jq` reading the ten fields of 2.2 off each line of `inbox.jsonl` directly. Event: the same loop run once by pi-loops started directly and once by pi-loops started on demand by a pi driven over rpc; the two `run_end` payloads have the same fields and the same run values.
+4. **Private state cleared** `test/contract/4-private-state.sh`: after one run, delete everything in the loops directory that 2.1 does not name as instance data and start pi-loops again. Pass: it runs the loop again and the earlier findings are unchanged field for field.
 5. **Contract size** `test/contract/5-size.sh`: section 2 has no more non-empty lines than the count frozen in this file's header. Pass when it does not. A line added there must name, in the CHANGELOG, the mechanism it replaced.
 
 ## 6. Mapping of requirements and features

package/README.md

@@ -5,7 +5,7 @@ English · [中文](README.zh-CN.md)
 An automation layer for [pi](https://github.com/earendil-works/pi), shipped as a plain pi extension.
 Nothing in pi is patched.
 
-![Two runs of the same loop in pi's browser window: the first ends "0 findings — nothing to report", the second reports one new TODO item, and /inbox lists what is waiting](docs/screenshot.png)
+![The pi-loops page: a decision and two findings from the project's loops beside a conversation, and the two loops on the right](docs/screenshot.png)
 
 A loop wakes up with the notes its last run left, does the work in a sub-agent that starts clean,
 and files what it found. You read the findings when you want to, and claim the ones worth a turn.
@@ -31,8 +31,9 @@ reaches you is what changed rather than everything that is there.
 
 Node ≥ 22.6 (pi loads the TypeScript sources directly) and pi ≥ 0.84.3 to load it into — 0.85 is
 what this is tested against, and an older pi is refused at load with a line that names the version
-it needs, rather than a link error naming one missing export. Nothing else: pi-loops has no
-runtime dependencies. What you do want first is a provider you can actually talk to — run `pi`, send
+it needs, rather than a link error naming one missing export. The process that runs your loops always
+runs on node, also when pi runs under bun: it then uses the `node` on your PATH. Nothing else:
+pi-loops has no runtime dependencies. What you do want first is a provider you can actually talk to — run `pi`, send
 one message, make sure you get an answer. pi-loops runs sub-agents while you are not watching, and
 the first sign of credentials that do not work should not be an empty inbox tomorrow morning.
 
@@ -45,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
@@ -60,36 +61,28 @@ when to reach for `cron_create`, `new_trigger` and the inbox on its own.
 
 Every morning a fresh sub-agent runs with the notes it wrote last time, does the work, and hands
 back two things: the notes for tomorrow, and any finding worth your attention. The notes go to a
-Markdown file, the findings go to the inbox, and your conversation is never touched. (The run says
-which is which in tags that a program reads rather than you — [docs/loops.md](docs/loops.md) has
-them.) Here are two runs of that loop, half an hour apart — the first:
+Markdown file and the findings go to the inbox. (The run says which is which in tags that a program
+reads rather than you — [docs/loops.md](docs/loops.md) has them.) Your conversation gets one line
+for each of the loop's first three runs, so you see that it works, and one for any run that fails;
+every other run is a line in the panel above the editor and in the page's loop activity strip. Here
+are two runs of that loop, half an hour apart, as the panel lists them:
 
 ```text
-cron todo · 5s · $0.000 · 0 findings · state updated
-md5 unchanged (`06ff2ec8af3668bb89ecc6580110ecad`), git rev still `15b6562`. No new unchecked items — nothing to report.
-/cron trace todo · /inbox
+Runs
+09:30 todo · 4s · 1 finding
+09:00 todo · 5s · 0 findings
 ```
 
-The second, after one commit:
-
-```text
-cron todo · 4s · $0.000 · 1 finding · state updated
-md5 changed (06ff2ec8… → fe00aaad…). One new unchecked item appeared.
-• TODO.md: new unchecked item — cache the /search results for 60s (commit 395a124 "todo: cache search results")
-/cron trace todo · /inbox
-```
-
-The first run found nothing worth saying and said nothing; the second noticed one change and
-reported only that. That is what the notes between runs buy — without them every run reports the
+The first run found nothing worth saying and filed nothing; the second noticed one change, a new
+unchecked item in TODO.md, and filed only that. That is what the notes between runs buy — without them every run reports the
 whole file every morning, and you stop reading it by Thursday. What they filed waits in the inbox:
 
 ```text
 /inbox
 Inbox (/tmp/acme-api, 3 new, times +00:00):
-  1. [inb-aae794d5] TODO: rate-limit the /search endpoint (unchecked, no owner)  (acme-api, cron:cron-b91def87, 2026-09-12 05:25)
-  2. [inb-3216a92d] TODO: retry the payment webhook on 5xx (unchecked, no owner)  (acme-api, cron:cron-b91def87, 2026-09-12 05:25)
-  3. [inb-74b73c72] TODO.md: new unchecked item — cache the /search results for 60s (commit 395a124 "todo: cache search results")  (acme-api, cron:todo, 2026-09-12 05:28)
-claim with /inbox claim <n>, dismiss with /inbox dismiss <n>
+  1. [inb-aae794d5] TODO: rate-limit the /search endpoint (unchecked, no owner)  (acme-api, cron-b91def87, 2026-09-12 05:25)
+  2. [inb-3216a92d] TODO: retry the payment webhook on 5xx (unchecked, no owner)  (acme-api, cron-b91def87, 2026-09-12 05:25)
+  3. [inb-74b73c72] TODO.md: new unchecked item — cache the /search results for 60s (commit 395a124 "todo: cache search results")  (acme-api, todo, 2026-09-12 05:28)
 ```
 
 The third finding is the run above; the two over it came from another loop in the same checkout,
@@ -175,31 +168,39 @@ Set a cap in `~/.pi/agent/loops/config.toml` before you rely on it:
 daily_budget_usd = 5.0
 ```
 
-When the last pi quits, a headless host takes over the clock so the 9am run happens whether or not
-you are at the machine, and hands it back the next time you open pi (`/cron host`,
-`pi-loops host status`). If you would rather it did not, put `[host] auto = false` in the same file.
+A pi window starts pi-loops in the background when there is work to run. It runs every loop, rule
+check and push, whether or not a window is open. It also runs the plain jobs of closed
+conversations, in those conversations; each such run is a model turn. A window runs the plain jobs
+of the conversation it holds. After a reboot, work resumes when a pi window opens, or at login if
+you run `pi-loops start --foreground` from your own systemd unit ([docs/cli.md](docs/cli.md)).
+`/pi-loops status` shows its status; `[host] auto = false` disables automatic starts.
 
 ## 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] 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            # from inside pi, where the extension is already loaded
+/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
@@ -208,17 +209,17 @@ pi-loops --tui                        # the terminal one, when you want it
 pi-loops --continue                   # pick up the newest session in this directory
 ```
 
-`pi-loops sessions|inspect|export|import` and `pi-loops host status|abort|stop` need no pi session
-open at all. They are for backups from cron or CI, restoring on a fresh machine, and looking in on
-the headless host. See [docs/cli.md](docs/cli.md).
+`pi-loops sessions|inspect|export|import` and `pi-loops start|stop|restart|status|abort` need no
+pi session open at all. They are for backups from cron or CI, restoring on a fresh machine, and
+looking in on pi-loops, which the page also shows as its Background view (`pi-loops status --url`). See [docs/cli.md](docs/cli.md).
 
-At a local terminal the bare command opens the browser front end; over ssh, or with no terminal at
+At a local terminal the bare command opens the browser page; over ssh, or with no terminal at
 all, it runs pi itself, because a browser on the far machine helps nobody. Pass `--web` or `--tui`
 when that guess is wrong. Anything else you pass goes straight to pi (`pi-loops --model
 anthropic/claude-opus-5 -e .`).
 
-Both windows are complete pi sessions — the browser one runs `pi --mode rpc` behind a page — so the
-session file, `--resume`, your models, tools and extensions are the same either way, and the model
+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, `--resume`, your models, tools and extensions are the same either way, and the model
 and thinking level you last chose start the next session whichever window it opens in. The browser
 one is a session and not a viewer: what a person can still do after the window changed is a release
 gate, and [docs/web-ui-parity.md](docs/web-ui-parity.md) has it line by line.
@@ -228,15 +229,21 @@ earlier one in this project, **compact** summarises what is there and says what
 or as `/clear`, `/new`, `/resume` and `/compact <what to keep>` in the composer. None of them
 deletes anything; the session you leave is a file that `resume` lists.
 
-It serves **`http://127.0.0.1:4173/`** by default, with a token that lives in a file, so the address
-is the same one tomorrow and is worth bookmarking (`--port` moves it if 4173 is spoken for). The
-first visit leaves a cookie and you never see the token again. Running `pi-loops` while one is
-already up opens that window instead of failing on the port; `--no-auth` drops even that, on a
-machine only you use.
+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). `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, `pi-loops --host 0.0.0.0` works too (and refuses
-`--no-auth`). Press **add device** in a browser that is already signed in and point the phone at the
+tailnet does TLS and identity. On the same wifi, `[page] host = "0.0.0.0"` in `config.toml` works
+too. Press **add device** in a browser that is already signed in and point the phone at the
 QR it shows: nothing to type, that device stays signed in, and the page can go on the home screen.
 
 ### Keeping it up to date
@@ -262,32 +269,58 @@ says what is in each one.
 
 ### Uninstall
 
+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.
+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:
+
+```bash
+pi-loops stop
+pi install npm:@alphacoder-v0/pi-loops@<version>   # <version> is 0.22.8
+```
+
+0.22.8 reads your jobs and rules as they are. It does not run the plain jobs of closed
+conversations, and it ignores the files that only later versions write, so nothing still waiting
+for a conversation is delivered: rule results, plain-job prompts waiting for their conversation, claimed
+findings, `/goal` continuations, recipe hand-offs, `inject_and_run` pushes and messages sent from
+the browser. Let them drain first (`pi-loops status` lists them). It also ignores the built-in
+tools later versions record on a loop, so a loop made in a chat with fewer of them runs with pi's
+default tools; and it has no window guard, so a plain job's prompt in an open window runs as your
+own message would, with no question before a dangerous command.
+
+The stop is remembered in `~/.pi/agent/loops/ui.json`, and 0.22.8 keeps it. After you upgrade again,
+pi-loops stays stopped until `pi-loops start`, or until `pi-loops` opens the browser page, which starts it.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `/cron add [--stateful] [--verify] "<schedule>" <prompt>` | Schedule a job: a plain job belongs to this chat and injects its result here (it sleeps while this session is not open), `--stateful` makes a loop that runs wherever the clock is, with memory and inbox routing, `--verify` adds the checker |
+| `/cron add [--stateful] [--verify] "<schedule>" <prompt>` | Schedule a job: a plain job belongs to this chat and injects its result here; `--stateful` makes a loop that runs in the background, with memory and inbox routing; `--verify` adds the checker |
 | `/cron`, `/cron all` | This project's jobs, or every project on this machine |
 | `/cron enable\|disable\|remove <ref>` | Pause, resume or delete one job — and write an audit entry into the session, as `add` does. `remove` takes a name of this project or the exact id of a job anywhere, so a name never reaches a checkout you are not in |
 | `/cron disable --all` | Pause every job in this project (`--all-projects` for the machine); `/cron enable --all` resumes |
-| `/cron run <ref>` | Fire one job now instead of waiting for its schedule |
+| `/cron run <ref>` | Ask pi-loops to run a loop now; plain jobs run now only in the window holding their conversation |
 | `/cron state <ref>` | The loop's notes — the Markdown it carries from one run to the next |
 | `/cron runs [ref]` | The run log: when it fired, what it cost, what it found |
 | `/cron trace <job> [k] [checker]` | The k-th latest run's full sub-agent transcript, maker or checker |
 | `/cron set <job> …` | Change a job in place — `--prompt`, `--schedule`, model, thinking, timeout, name — keeping its id, and therefore its notes |
 | `/cron cost [today\|7d\|all]` | What automation has cost, against `[limits] daily_budget_usd` |
-| `/cron scheduler` | Which pi process currently owns the timer |
-| `/cron host [start\|stop]` | The headless host that keeps the clock after the last pi quits |
+| `/cron scheduler` | This window, its conversation, and pi-loops status |
+| `/pi-loops start\|stop\|restart\|status` | Start, stop, restart or show pi-loops |
 | `/cron clear <ref>` | Release a run marker left behind by a process that is gone |
 | `/cron gc` | Remove plain jobs whose session was deleted (they are parked as disabled first) |
-| `/cron panel on\|off` | The side panel above the editor: Triggers, Inbox, Cron, MCP |
-| `/cron snapshot` | Write what only this process knows — connected MCP servers and their tools, active tools, hooks, who owns the clock — into the session as a `pi_loops_snapshot` entry, for a front end that is not a terminal |
+| `/cron panel on\|off` | The side panel above the editor: Rules, Loops, Runs, MCP |
+| `/cron snapshot` | Write what only this process knows — connected MCP servers and their tools, active tools, hooks, whether pi-loops is running and its pid — into the session as a `pi_loops_snapshot` entry, for a front end that is not a terminal |
 | `/inbox [list\|all\|claim <n>\|dismiss <n> [reason]\|clear] [--all]` | Triage findings from stateful loops. This project's by default, `--all` for every project — the same scoping `/cron` and `/triggers` use. A reason given with `dismiss` is shown to the loop's next run |
 | `/goal [<condition>]`, `/goal pause\|resume\|clear` | Hold the session to a stop condition: after every turn an evaluator with no tools decides whether it is met, and sends the agent back to work if not (max 8 continuations). Bare `/goal` shows the one in force |
 | `/new-trigger <natural language>` | Create a condition-based rule ("when ~/build.done exists, run cargo test") |
@@ -299,7 +332,8 @@ State stays in `~/.pi/agent/loops` until you delete it.
 | `/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
@@ -329,7 +363,7 @@ notifications, and lifecycle hooks — each has a page here.
 - [docs/goal.md](docs/goal.md) — `/goal`: holding a session to a stop condition
 - [docs/recipes.md](docs/recipes.md) — `/recipe`: a project run on loops, installed in one command; the issue loop and autoresearch, and how to write your own
 - [docs/session-archive.md](docs/session-archive.md) — `/session-export`, `/session-import`
-- [docs/cli.md](docs/cli.md) — the `pi-loops` command line: export, import, the inbox, and looking in on the host
+- [docs/cli.md](docs/cli.md) — the `pi-loops` command line: export, import, the inbox, and looking in on pi-loops
 - [docs/downstream.md](docs/downstream.md) — what a program may depend on: a recipe directory, `run_start` / `run_end`, `pi-loops inbox --json`; nothing else
 - [docs/web-ui-parity.md](docs/web-ui-parity.md) — what the browser front end owes you, line by line
 - [docs/configuration.md](docs/configuration.md) — paths, `config.toml`, flags, environment
@@ -349,9 +383,11 @@ notifications, and lifecycle hooks — each has a page here.
 | `~/.pi/agent/loops/logs/pi-<pid>.log` | what each pi process's automation did |
 | `~/.pi/agent/loops/triggers.json`, `triggers-audit.jsonl` | dynamic rules and trigger audit |
 | `~/.pi/agent/loops/{config,mcp,hooks}.toml` | configuration |
-| `~/.pi/agent/loops/scheduler.json` | which pi process currently owns the timer |
+| `~/.pi/agent/loops/host-service.json`, `host.log` | pi-loops record and log |
+| `~/.pi/agent/loops/leases/`, `requests/` | where each conversation is open, and what waits to be delivered to it |
+| `~/.pi/agent/loops/pages/` | one record per conversation open in the browser page: its pi's pid, and when a tab last used it |
 
-Set `PI_LOOPS_DIR` to relocate all of it. The notes are yours to edit when the agent got something
+[docs/configuration.md](docs/configuration.md) lists every file. Set `PI_LOOPS_DIR` to relocate all of it. The notes are yours to edit when the agent got something
 wrong, and `logs/pi-<pid>.log` is the file to read after an overnight failure.
 
 ## Automation outlives the window it was set up in
@@ -359,19 +395,19 @@ wrong, and `logs/pi-<pid>.log` is the file to read after an overnight failure.
 Scheduled work is only worth trusting if it survives you closing the editor. So "pi was restarted"
 is treated here as the normal case rather than the exception.
 
-Jobs are machine-global and never expire. Any open pi can own the timer:
-leadership is a file with a heartbeat, and when the process holding it exits or dies, the next tick
-in another window picks it up. A project's trigger checks run in a pi that is open in that project,
-so a result that belongs in a conversation lands in the right one. A tick a loop missed while
-nothing was running is caught up once, collapsed rather than replayed; a plain job's is not, because
-its prompt was written for a conversation that is gone (`--catchup` and `--no-catchup` override
-either way).
-
-Sub-agents are sessions opened inside the interactive pi through its SDK, not child processes: they
-share its live MCP servers — the browser tab that is already logged in, the database session that is
-already open — along with its extensions, model and thinking level. The headless host has no parent
-session to share, so its runs connect their own MCP clients from `mcp.toml`: a server that was live
-only because you had a window open is not live at 3am.
+Jobs are machine-global and never expire. A window starts pi-loops in the background when there is work to run. It runs stateful loops, rule checks and MCP pushes;
+a window runs the plain jobs of the conversation open in it, and pi-loops runs those of
+closed conversations. Rule results go to the conversation that created the rule; if it is closed,
+pi-loops appends the result to it. The inbox gets a result only when that conversation cannot be
+written. A tick a loop
+missed while pi-loops was not running is caught up once, collapsed rather than replayed; a plain
+job's is not, because its prompt was written for a conversation that has moved on (`--catchup` and
+`--no-catchup` override either way).
+
+Sub-agents are sessions opened through pi's SDK inside the process that runs them, not child
+processes. Loops and rule checks run in the background, which has no window to share: their runs connect
+their own MCP clients from `mcp.toml` and the project's own servers, so a server that is live only
+because you had a window open is not live to a loop at 3am.
 
 [docs/design.md](docs/design.md) has the architecture and the reasoning behind each of these.