@alphacoder-v0/pi-loops 0.17.3

package/docs/triggers.md

@@ -0,0 +1,140 @@
+# Dynamic triggers
+
+## Rules
+
+A rule is a natural-language **condition** and **action**:
+
+```text
+/new-trigger when ~/build.done exists, run cargo test and show me the result
+/new-trigger 当 $HOME/helloworld 存在的时候，打印它的内容
+```
+
+`/new-trigger` asks the agent to extract condition and action and call the `new_trigger` tool
+(the agent may also do this from ordinary chat). Rules **fire once** by default (`fire_once=false`
+for repeating), and their output stays in the TUI and audit unless `promote_to_chat` is set.
+Time-based requests ("every hour", "daily", "定时任务") are refused and routed to `cron_create`.
+
+Tools: `new_trigger` (condition, action, spec, fire_once, promote_to_chat), `list_triggers`,
+`remove_trigger` (id | all), `set_trigger_state`. Creating, removing and re-enabling ask the user to
+confirm, with `ctx.ui.confirm`.
+
+The model-facing tools see the calling project only: `list_triggers` takes `all_projects: true`
+when the user asks about the rest, and `remove_trigger { all: true }` clears this project's rules,
+never the machine's.
+
+## Evaluation
+
+While at least one enabled rule exists, every `poll_interval_secs` (default 600; `--trigger-poll-secs`
+or `config.toml`) one sub-agent per project that has rules is started — by a pi open in that project
+(the session that created the rules if it is open, otherwise the lowest pid there), or by the
+machine leader when no pi is open in the project. The check receives the
+event JSON and every enabled rule and is told to inspect the filesystem, commands, clock or network
+as needed, execute the actions of matching rules, and reply `matched dyn-…` or exactly
+`no dynamic trigger rule matched`. Matched fire-once rules are disabled with `fired_at`.
+
+Pushed MCP notifications (see [mcp.md](mcp.md)) enter the same runtime and are evaluated against
+the rules unless the server is configured as an `inject_summary` / `inject_and_run` feed.
+
+A rule whose check keeps failing is polled with a widening gap instead of at every interval: after
+three failed checks in a row the rule waits 5 minutes, then 10, 20, … up to 6 hours (the scheduler's
+job backoff, same numbers — literally the same function, `backoffWaitMs` in `src/schedule.ts`).
+The count lives on the rule (`consecutive_failures`,
+`last_check_failed_at`), a check that completes clears it — including `/triggers run <id>`, which is
+the way to retry a backed-off rule now — and entering the backoff is audited as `backoff` with the
+rule ids and the failure count. Pushes are unaffected: an event is worth one attempt.
+
+## What happens when the machine is busy or over budget
+
+A trigger that finds every check slot taken (`[cron] max_concurrent_runs`, default 3) or the day over
+`[limits] daily_budget_usd` is refused before it claims the dedup key, and what happens next depends
+on what was refused:
+
+- A **periodic check** is dropped (`deferred`). The next poll looks at the world again and reaches
+  the same conclusion, so re-running the held one would only check twice.
+- A **push** refused for want of a slot is held in a bounded list (32 events, keyed by idempotency
+  key and project) and retried oldest first on the next scheduler tick — a push is an event that
+  happened once and no server re-sends it. Its audit row says `deferred` with `queued` (`queued`,
+  `replaced` when the envelope's `latest_replaces` policy supersedes one already waiting,
+  `collapsed` when it does not) and the current `pending` depth. The retry goes through dedup,
+  audit and the normal delivery, and its check prompt carries the event's original `received_at`
+  plus `deferred_ms` and a line saying how long it was held, so a time-sensitive rule can re-check
+  before acting. When 32 are already waiting, the **oldest** is dropped with its own `dropped` row.
+- A push refused because the day is **over budget** is dropped (`budget_exceeded`), not held: too
+  busy clears in minutes, but the cap can last until midnight, and acting on the morning's event at
+  23:59 is worse than not acting. The same applies to a held push whose retry finds the cap
+  exceeded. Held pushes live in memory, so they do not survive the process quitting.
+
+## Promotion and audit
+
+A matched rule with `promote_to_chat` inserts `[Trigger <trace>] <result>` into the chat context
+of the pi that ran the check (visible to future turns; no model call when idle, a follow-up turn
+when the agent was busy). Because checks run in the rule's project, that is the right chat; only
+when no pi is open there does the result go to the inbox (`redirected`). One check evaluates every
+rule of the project at once, so it runs under **one** model: the first rule that has one recorded
+(`/triggers set <id> --model … | -`), and that rule's thinking level with it — a thinking level
+belongs to the model it was chosen for, and a rule with a model but no level falls back to the
+running session's. Pin the model on the rule you want to decide it, or on all of them. The timeout is
+the longest of the project's rules (`--timeout`), else `[triggers] run_timeout_secs`. Every trigger leaves audit records in `triggers-audit.jsonl` and as
+session entries (`trigger`, `trigger_result`, `trigger_promotion`); `/triggers audit [N] [--all]`
+shows this project's rows with decisions and transcript paths. The complete set of states:
+
+- admission — `accepted`, `deduped`, `deferred` (no slot, or handed to the pi that owns the rules),
+  `taken_over` (the owner did not claim it), `dropped` (the held list was full), `budget_exceeded`,
+  `cycle_suppressed` (it reached a sub-agent), `backoff`, `disabled` (the rule's project is gone);
+- the run — `running`, then `completed` / `failed` / `aborted`, or `no_rules`;
+- promotion — `promoted`, `redirected` (to the inbox: no pi open in that project), `skipped` (no
+  matched rule has `promote_to_chat`).
+
+Rows of type `cron_control_plane` use the operation as the state instead: `add`, `enable`,
+`disable`, `remove`.
+
+A 5-minute dedup window collapses repeated events with the same idempotency key (per project for
+rule evaluation, per window for injected pushes).
+
+```text
+/triggers status      rule counts, checker ownership, last check, push sources
+/triggers rules       this project's rules  (--all for every project)
+/triggers sources     local checker + each MCP server: state, queued/dropped/deduped, tools
+                      (/triggers hooks is the same view)
+/triggers enable <id> /triggers disable <id> /triggers remove <id>   also --all | --all-projects
+/triggers set <id>    --model | --thinking | --timeout | --host: what the action runs with
+/triggers run <id>    check one rule now, without waiting for its poll slot
+/triggers running     sub-agents in flight (dynamic checks and cron runs)   /triggers abort <trace>|--all
+/triggers audit [N]
+/triggers panel on|off
+/triggers help        all of the above, in the terminal
+```
+
+Cron runs share this runtime's views: they appear in `/triggers running` and `/triggers audit`
+and can be aborted by run id.
+
+`/triggers run <id>` takes the same path a periodic check takes — dedup, audit, the check
+sub-agent, promotion — and skips only the poll ledger, which is what running it now means. The
+poll interval is unaffected: the next scheduled check happens when it would have anyway.
+
+## 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` and `cron_remove` work and the control-plane audit records
+`actor: sub-agent`. 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).
+
+## Command output, approvals, promotion
+
+`/triggers enable|disable <id>` prints the rule's state, condition and action (and the
+fire-once note); `/triggers sources` lists MCP servers, the cron hook and the dynamic
+checker in registration order with a `sources: N total, M connected, K require
+attention` summary in `/triggers status`. Errors are worded once and kept that way (`unknown /triggers command:
+…`, `usage: /triggers remove <id>|--all`, `/new-trigger` parse messages). `/triggers remove --all`
+clears this project's rules; `--all-projects` is the explicit machine-wide sweep.
+
+Prompt-class tool calls (`new_trigger`, `remove_trigger`, re-enabling a trigger or a cron job)
+show an approval card — Action, Tool, a value-free Reason, an args hash and a redacted
+Preview — and leave `approval required` / `approved` / `denied` lines in the feed. Promoted
+results and injected summaries are inserted as `[Trigger <trace>] <text>`, with no extra
+wrapper; an inject-and-run turn announces itself with
+`running triggered turn (trace …)`.

package/docs/troubleshooting.md

@@ -0,0 +1,111 @@
+# Troubleshooting
+
+**Nothing fires.** `/cron scheduler`: is this process the timer owner or standby? If the owner died
+without cleanup, a standby takes over within 90 seconds. Jobs show `next …` when enabled. A plain
+job marked `[dormant …]` only fires in the session that created it (`--resume` it); a loop marked
+`[orphan: cwd missing]` was disabled because its checkout is gone.
+
+**A run failed.** `/cron runs` shows the error; `/cron trace <job> 1` shows the sub-agent's
+transcript; `pi --session <file>` resumes it. Sub-agents run inside your interactive pi with its
+credentials, tools and MCP servers; they cannot answer permission prompts (use `--tools` to restrict).
+
+**Findings never arrive.** The loop must end its reply with `<inbox>…</inbox>` tags; check
+`/cron trace`. Quiet runs are normal. With `--verify`, dropped findings and reasons are on the run
+card and in `/cron trace <job> 1 checker`.
+
+**`Tool "cron_create" conflicts with …`, and pi exits.** The package is installed twice, and this
+is fatal rather than cosmetic: the second copy fails to load and pi stops. It happens easily —
+a local checkout you are working on plus `pi install git:…` of the published one both sit in
+`packages` in `~/.pi/agent/settings.json`, and both register the same tools. (An older, milder
+symptom of the same thing was commands appearing as `/cron:1`.)
+
+Keep one:
+
+```bash
+pi remove git:github.com/alphacoder-v0/pi-loops    # keep the checkout you are working on
+pi remove /path/to/your/checkout                   # or keep the installed one
+```
+
+Then re-run the launcher install from the copy you kept: `install-launcher` writes the path of
+whichever copy ran it, so removing that one leaves `pi-loops` pointing at a package that is no
+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.
+
+**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
+TLS) or start with `pi-loops --host 0.0.0.0` for a phone on the same wifi. See
+[cli.md](cli.md#from-a-phone).
+
+**The QR is offered but scanning it goes nowhere.** The QR encodes the address *the browser you
+pressed the button in* is using. Press it in a window that is on `127.0.0.1` and there is no
+address a phone could use — it says so instead of drawing one. Open the tailnet or LAN address on
+the desktop first, then press it there. Where the machine has several addresses, the dialog lists
+them with the interface each belongs to; a docker or libvirt bridge is not the one.
+
+**"port 4173 is already in use" — or a second `pi-loops` opened the first one's window.** Starting
+a second session while one is up hands you the window that is already there rather than failing.
+That is deliberate. `--port <n>` starts a genuinely separate one, and the browser stays signed in:
+the token is the one file both of them read, and a cookie is not scoped to a port — `localhost:4173`
+and `localhost:4180` are the same site to a browser, which is the fact the `Sec-Fetch-Site` check
+here is built around. A `--port` that is not a number is refused rather than quietly served on 4173.
+
+**A pairing code stopped working.** They last ten minutes, are good for one use, and closing the
+dialog retires the one it was showing. Twenty wrong guesses disable pairing until another code is
+made. Press **add device** again.
+
+**Every device was signed out at once.** Something removed `~/.pi/agent/loops/web-token`, or
+`PI_LOOPS_DIR` points somewhere new — the token is that file, and the cookie every device holds is
+its contents.
+
+**The window stops answering — you type, your message appears, no reply ever does.** The event
+stream is numbered per run of the server process, so a page that was open across a restart can end
+up counting against numbering that no longer exists and skip everything the new process sends,
+while still polling happily and looking alive. From 0.12.2 the page notices this by itself, within
+a few seconds, and says "the conversation above was reloaded". A page older than that has to be
+reloaded by hand — the fix cannot reach a tab that was already open when it was installed.
+
+Reloading the plain address is enough: the page is served `no-store`, so a normal refresh always
+fetches the current one, and the token in the URL is only needed by a browser that has never been
+here. From 0.12.4 a window that is older than what is installed says so in a bar across the top.
+
+**MCP server shows `disconnected` / `auth_failed`.** `/triggers sources` has the last error.
+Bearer tokens come from `$TOKEN_REF` or pi's credential store; endpoints must be https except
+127.0.0.1. Custom notifications without `_meta.pi_dedup_key` are dropped and counted.
+
+**Hooks do not run.** Startup warnings list malformed rules. Project hooks need
+`allow_project_hooks = true`. Hooks fire only in the interactive pi, not in sub-agents.
+
+**`/session-export` says the session is ephemeral.** pi writes the session file after the first
+message; `--no-session` sessions cannot be exported.
+
+**Costs.** A stateful run is one sub-agent call (~$0.04 with gpt-5.5); `--verify` adds a second;
+a dynamic check runs only while enabled rules exist. `every 1m` loops add up — prefer hourly or
+daily schedules for anything that is not a test. `/cron cost` adds up the run log;
+`[limits] daily_budget_usd` stops dispatching once the day reaches it, and says so on the job. It
+also stops a run that is already going when its own cost would carry the day past the cap — that
+run is recorded as aborted rather than failed, so the slot is still owed and the job's failure
+streak is untouched; it simply will not be dispatched again until the day rolls over or the cap is
+raised.
+
+**`pi-loops host status` says the host "is not answering" but it is running.** Before 0.4.0 this
+happened whenever `PI_LOOPS_DIR` was deep: a unix socket path is capped at 108 bytes, so
+`<dir>/host.sock` failed to bind and the control channel silently did not exist. It now falls back
+to a short path under a per-user directory in the temp directory. If you still see it, the host is
+genuinely wedged — `host.log` has its last line, and `pi-loops host stop` escalates to SIGTERM.
+
+**A host is running that you did not start.** That is the design: the last interactive pi to quit
+hands the clock to a headless host when there is work for it (an enabled loop or rule for this
+machine, or an MCP server that pushes). `pi-loops host status` says what it is doing and what it
+has spent; `pi-loops host stop` ends it; `[host] auto = false` stops the hand-off happening at all.
+After testing with a throwaway `PI_LOOPS_DIR`, remember that the host it spawned outlives the pi
+that spawned it — it is polling and billing against *that* directory until stopped.
+
+**The browser front end refuses a slash command.** It drives `pi --mode rpc`,
+where pi's own built-in commands do not exist — only extension commands and skills do. Typing one
+is refused with a pointer to the button that does the same thing rather than being passed to the
+model as text. `/login` is the one with no equivalent at all: log in once with `pi` in a terminal,
+then start the front end.

package/docs/web-ui-parity.md

@@ -0,0 +1,305 @@
+# What the browser front end owes you
+
+`pi-loops` opens a browser window instead of a terminal one when you are at a local terminal. That
+makes the page an alternative to the TUI, not a lesser chat box bolted onto the side of it — and the
+difference between those two things is a list, kept here, of what a person can still do after the
+window changed.
+
+This is a gate, not a wish list. Anything below is either implemented, or marked as held with the
+reason. A release that drops one of these silently is the failure this file exists to prevent.
+
+Where a line is enforced by a test, the test is named. The rest are checked by reading, which is
+weaker, and worth converting whenever one of them breaks.
+
+## Sending, and what happens while it runs
+
+- [x] Enter sends. Shift+Enter inserts a newline.
+- [x] Enter does nothing while an input method is composing — typing Chinese, Japanese or Korean
+      means Enter picks a candidate, not "send". `test/web-page.test.ts`: *Enter while an input
+      method is mid-word does not send*.
+- [x] Submitting while a turn is running queues instead of racing it, the way the TUI does.
+- [x] The queue is visible and can be cleared.
+- [x] Abort stops the current turn.
+- [x] Busy, queued count, and "pi exited" are all visible without opening a terminal.
+      `test/web-page.test.ts`: *a tool call and a dead pi both reach the page*.
+- [x] Prompt history: ArrowUp and ArrowDown, but only while the caret is on the first or last line,
+      so they still navigate a multi-line draft.
+
+## Composing
+
+- [x] `/` completes slash commands; `@` completes paths, and the mention is expanded before the
+      prompt is sent — the expansion is anchored to the session's directory, not to anything the
+      browser supplies.
+- [x] A command with an argument can be typed straight through. The completion list closes on the
+      space, and an answer still in flight does not put it back — which it did, so Enter accepted
+      the completion instead of sending the line and anything taking an argument was mouse-only.
+      `test/web-page.test.ts`: *a completion answer in flight does not reopen a list the space just
+      closed*.
+- [x] A command that takes no argument runs on one Enter, the way it does in a terminal. When what
+      you have typed is already the whole of the highlighted completion there is nothing left to
+      accept, so Enter sends the line; a shorter prefix still gets completed, and Tab only ever
+      inserts. `test/web-page.test.ts`: *Enter on a command already typed in full sends it instead of
+      completing it again*.
+- [x] Images: attach, paste, and a strip showing what is attached, each with a visible way to take
+      it off again. An image-only prompt is valid; ten per message is the cap, and it says so. PNG,
+      JPEG, GIF, WebP and AVIF, the same set however it arrived — anything else is refused with the
+      same visible notice rather than sent under a type it is not.
+      `test/web-page.test.ts`: *a message carries at most ten images*, *an image type the page cannot
+      render is refused rather than sent as a broken PNG*.
+- [x] A tap on a composer button lands on that button, even with a soft keyboard open — tapping it
+      blurs the box, which dismisses the keyboard, which moves everything.
+      `test/web-page.test.ts`: *a phone's soft keyboard cannot steal the tap on send*.
+
+## What the feed shows
+
+- [x] Assistant text, thinking, tool calls, tool results, errors, and the end of a turn.
+- [x] The conversation is what the conversation is for. A whole stretch of work — thinking and tool
+      calls, interleaved as they arrive — is **one** row, closed: what is happening while it happens,
+      what happened afterwards. One button in the header opens or closes every one of them.
+      `test/web-page.test.ts`: *a stretch of work is one row, and one button opens every one of
+      them*.
+- [x] Replies render as Markdown — headings, lists, quotes, rules, tables, inline code, fenced
+      code, and http(s) links. Everything is escaped first: a reply is not trusted input, and a
+      tool result quoted inside one is whatever some web page said. `test/web-page.test.ts`: *a
+      reply is rendered as Markdown, and cannot smuggle markup through it*.
+- [x] Terminal escape sequences are stripped rather than shown. Plenty of what reaches a session
+      was written for a terminal. `test/web-page.test.ts`: *terminal escape codes do not reach the
+      screen as text*.
+- [x] Your own message appears once, whether the page drew it or pi echoed it back.
+      `test/web-page.test.ts`: *your own message is drawn once*.
+- [x] Text selection works, and is never destroyed by an update: the feed is appended to, never
+      rebuilt. The cost of appending is that a missed event leaves a hole, so events are numbered
+      and a gap reloads the transcript rather than drawing on top of one. A page that stops being
+      told anything at all notices that from its own polling, rather than sitting there looking
+      alive. `test/web-page.test.ts`: *a page that stops receiving events notices by itself*.
+      `test/web-page.test.ts`: *a gap in the event stream reloads the conversation*.
+- [x] While you are reading back through the conversation, an update never yanks the page — and
+      never arrives silently either: there is a way back to the newest.
+- [x] Every block says when it happened.
+- [x] Every message, tool call and result can be copied, including over plain http where the
+      clipboard API is unavailable. The button waits for a hover on a mouse and is simply always
+      there on a touch screen, which has no hover to wait for.
+- [x] Tool results, an extension's messages and pi's dying words are capped, and every cap says how
+      much was dropped — one helper for the three of them, because they used to report it three
+      different ways and one of them not at all, so a result that stopped at 8000 characters looked
+      like a result that ended there.
+- [x] **You can see what the session made, not only read about it.** A picture in a reply is a
+      picture — including one named in ordinary prose rather than as a link; a path is something to
+      open; a page written into the reply has a preview; an image a tool returned is shown rather
+      than dropped. `test/web-page.test.ts`: *a path written in prose becomes something to open*.
+      Everything served that way is anchored inside the session's directory — and inside `$HOME`,
+      because an agent asked to make something for a person leaves it where a person keeps things,
+      but there only for the types one *looks* at, so a service-account key named like ordinary JSON
+      is not previewed. Both roots exclude every dot segment and the directory holding the token.
+      Restricted to file types worth showing, and sandboxed into an opaque origin — a page the model
+      wrote can be looked at and cannot act.
+      `test/web.test.ts`: *a file the session made can be looked at, and nothing else can*.
+      `test/web-page.test.ts`: *a reply can show a picture*, *an image that came back from a tool*.
+- [x] A tool call and what it returned are one block, and it starts closed. A tool that prints two
+      hundred lines must not push the conversation off the screen to do it.
+      `test/web-page.test.ts`: *a run of tool calls is one row, and the next run is a new one*.
+- [x] You are on the right in a bubble and the model is full-width prose: the shape says who is
+      speaking before a word is read. Status lines are small, monospace and quiet — context, not
+      conversation.
+- [x] The conversation has a reading width. A line the width of a 27-inch monitor is not readable.
+- [x] An empty session says what it is and what to type, rather than being a blank rectangle —
+      which is also the first thing a newly paired phone shows, and what is left when the last
+      message is undone: a line the page wrote about itself is not a conversation.
+      `test/web-page.test.ts`: *an empty session says what it is*, *undoing the only message shows
+      the empty state*.
+
+## Automation, which is the reason this project exists
+
+- [x] Jobs, loops and rules: what they are, whether they are enabled, and what the last error was.
+- [x] **What this project has is what this project has, and the rest is counted rather than
+      dropped.** The store is machine-wide and this list is not, so a job made in another directory
+      says so as a count — without it, a job somewhere else is indistinguishable from a job that is
+      gone. Jobs and rules are counted and labelled apart, each line naming the command that lists
+      them (`/cron all`, `/triggers rules --all`): one number covering both agrees with neither
+      command, and the line exists to send you to the command. A job stamped with a hostname this
+      machine no longer has (a rebuilt container, a rename) is listed and marked, the way `/cron`
+      lists it, rather than filtered out of sight.
+      What counts as "this project" is what the extension says it is — symlinks resolved, `$HOME`
+      too broad to be one — because a panel that disagrees with the command is worse than either.
+      `test/web.test.ts`: *the panel and /cron agree about what this project is*.
+      `test/web-page.test.ts`: *a job this machine no longer owns is listed, not hidden*.
+- [x] **When each job runs next, whatever its schedule.** The page used to work this out itself and
+      understood only `every <interval>`, so a job on `0 9 * * *` — the first example in the
+      README — showed nothing. A second cron parser in a page with no dependencies was the wrong
+      fix: the process that owns the clock has the evaluator, and writes the answers to
+      `next-runs.json` beside the store when one of them changes. A time that has already passed is
+      shown as no next run rather than as a past one, a job that is disabled or belongs to another
+      machine is not promised one, and a next run that is not today says which day it is.
+      `test/scheduler.test.ts`: *the leader writes when each job runs next*.
+      `test/web.test.ts`: *the panel shows the next run of a cron-expression job*.
+      `test/web-page.test.ts`: *a next run in April does not render as a time of day*.
+- [x] The name of a job is never abbreviated: it is what `/cron set <name> …` takes, so a clipped
+      one is a name you cannot act on. It wraps; the schedule beside it does not break in half.
+- [x] Run a job now.
+- [x] Inbox count.
+- [x] Runtime: scheduler state and whether this pi owns the clock, MCP servers and their state,
+      hook count and events, tool count, last poll, snapshot age and version.
+- [x] A count leads to the list behind it — "24 tools" answers the wrong question on its own.
+      `test/web-page.test.ts`: *a count in the panel leads to the list behind it*.
+- [x] Goal state and the session's own metadata.
+- [x] A malformed job in a store file does not blank the panel. `test/web-page.test.ts`: *a job
+      with the wrong types in it does not blank the sidebar*.
+- [x] On a narrow screen the panel is a drawer, not something that disappears: what a loop is doing
+      is the reason to open this on a phone.
+- [x] Thirteen controls do not fit across a phone. The ones you reach for mid-conversation stay in
+      the header; the rest move — not copy — into a sheet behind one button.
+      `test/web-page.test.ts`: *the header's secondary actions move into a sheet and back*.
+
+## How it looks
+
+- [x] Light and dark are both designed: every surface is a named colour, not a translucent grey
+      over whatever the browser paints, so the page looks the same on a machine whose default
+      background is not white.
+- [x] The stored theme is applied before the first paint. Applied later, a dark page renders light
+      and then blinks. `test/web-page.test.ts`: *the stored theme is applied before the first
+      paint*.
+- [x] Prose is proportional and anything from a terminal is monospace — with CJK faces named in
+      both stacks, because the default fallback is neither the right shape for reading nor the
+      right width for a box someone drew with line characters.
+
+## Confirmations
+
+- [x] Anything an extension asks — select, confirm, input, editor, notify — is answerable in the
+      browser. A session whose only question is on a terminal you closed is a stuck session. One
+      asked while no browser was attached is held for a browser that turns up, and the list of those
+      is bounded the way the event backlog is: an abandoned dialog was otherwise re-offered every
+      eight seconds for as long as the process lived.
+- [x] A confirmation shows what is about to happen apart from the reasoning about it, so it cannot
+      be read as prose and waved through. `test/web-page.test.ts`: *a confirmation shows what is
+      about to run*.
+- [x] Enter does not approve: the focus starts on cancel.
+- [x] Clicking away from any dialog closes it. `test/web-page.test.ts`: *clicking outside a dialog
+      closes it*.
+
+## Session
+
+- [x] Model and thinking level, switchable, with the failure reported when credentials are missing,
+      and **remembered**: the next session starts on the model you last chose.
+      `test/cli.test.ts`: *the model you chose last time starts the next session*.
+      The picker is grouped by provider and says what decides the choice — the model's own name, its
+      context window, whether it takes images — with the ones you have used recently at the top. pi
+      only offers models from providers you have configured, so everything in it is usable.
+- [x] The model in use is in the picker even when pi's catalog has never heard of it. A session can
+      be running on a provider this machine has no credentials for, and pi lists only the ones it
+      does — so the picker had nothing to select and showed an empty control beside a panel naming
+      the model, which reads as "no model". It is offered under its own provider, marked as not in
+      the catalog so the reason is on the screen.
+      `test/web-page.test.ts`: *the model in use is in the picker even when the catalog has never
+      heard of it*.
+- [x] The thinking levels offered are the ones this model has — asked for per model rather than
+      drawn from one fixed list, because picking a level a model does not implement does nothing at
+      all.
+- [x] Attaching an image is refused, with the reason, by a model that cannot see one.
+- [x] Cost and token counts.
+- [x] Compact, undo (fork from your last message), find across the whole session including
+      abandoned branches, export to HTML, and share as a redacted gist. Undo reloads the
+      conversation through the one path every other thing that empties the feed uses, so an undone
+      session is as empty as a new one rather than a blank rectangle with a notice on it.
+      `test/web-page.test.ts`: *undoing the only message shows the empty state*.
+- [x] Compaction says what it did — what the context was and what it became, and what the summary
+      cost — and what it keeps can be steered: `/compact keep the API shapes`, as in the terminal.
+      A line that reports neither is a line asking to be taken on faith.
+      `test/web.test.ts`: *the compact button can steer what the summary keeps*.
+      `test/web-page.test.ts`: *clear, resume and compact are typed as well as clicked*.
+- [x] **Starting over does not mean going back to a terminal.** The context is finished with far
+      more often than the window is: a new session and going back to an earlier one are both here,
+      by button and by `/clear`, `/new` and `/resume` typed in the composer — the habit comes from a
+      terminal and the muscle memory arrives with it. Neither deletes anything: the session being
+      left is a file that `resume` lists, labelled by what was said in it rather than by a filename.
+      `test/web.test.ts`: *a new session is a path pi has not written yet, and going back is one it
+      has*. `test/web-page.test.ts`: *the session you are in is not offered as one to go back to*.
+- [x] A session started here is a session pi-loops recognises. pi names the sessions it starts after
+      their id and the front end cannot know that id in time, so anything identifying a session by
+      its file name is wrong about this one — which parked every inject-and-run cron job made in a
+      session started from the page. `test/store.test.ts`: *sessionExists scans pi's sessions root*.
+- [x] Nothing read off the disk can make a line say something other than what it is: terminal
+      escapes and the bidi overrides that reorder text are stripped from every name and message
+      shown, and the picker is where that matters most.
+      `test/web-page.test.ts`: *a name cannot reorder the line it is drawn on*.
+- [x] A session is not swapped out from under a turn that is running — the swap would abort it, and
+      losing a reply you are waiting for is not something to find out afterwards. The refusal is on
+      the server, so a tab left open across an upgrade cannot skip it.
+      `test/web.test.ts`: *a session is not swapped out from under a turn that is running*.
+- [x] Going back to a session puts it back on the model it was last using. A `--model` on the launch
+      command line — yours, or the remembered one the launcher adds — lasts as long as the process
+      rather than the session, so pi re-applies it on every swap and a resumed conversation landed on
+      a model it was never had with. A model whose credentials are gone is reported rather than
+      forced. `test/web.test.ts`: *going back to an earlier session puts it back on the model it was
+      last using*.
+- [x] `--continue`, `--resume` and `--session` reach pi unchanged, so a session moves between the
+      two windows.
+- [x] **Ending the window ends the session, properly.** Ctrl-C in the terminal that started it means
+      `/quit`, not a kill: pi is started in a process group of its own so the terminal's SIGINT
+      cannot reach it, is asked to shut down with the signal it does handle, and is waited for — which
+      is what hands the clock to the headless host and what puts the line saying so in front of you
+      before the window closes.
+      `test/web.test.ts`: *the pi behind the page runs in a process group of its own*, *Ctrl-C in that
+      terminal ends the session the way /quit does, and waits for it*.
+- [x] **And the terminal is told what became of the automation.** pi-loops announces the hand-off
+      through `ctx.ui.notify`, and `ctx.hasUI` is true in rpc mode — so the note is an event addressed
+      to a page whose server is the process on its way out, and the person who pressed Ctrl-C saw only
+      `pi exited (143)` while their loops kept running somewhere nobody had told them about. That note is
+      relayed to the terminal when it arrives; when it does not, the loops directory is read the way
+      `pi-loops host status` reads it — the live host and how to see or stop it, or that none started
+      and which log says why, or nothing at all when nothing was going to run.
+      `test/web.test.ts`: *Ctrl-C says where the automation went, when pi's own note never arrives*,
+      *pi's own word on the hand-off reaches the terminal when it arrives in time*.
+- [x] **A window older than what is installed says so, across the top, with the button that fixes
+      it.** A tab left open across an upgrade looks exactly like a current one — the panel even
+      shows a version, but that is the server's, read live — and three rounds of "no reply appears"
+      were spent on a page that could not have received one.
+      `test/web-page.test.ts`: *a page left open across an upgrade says so*.
+
+### Held, with the reason
+
+- **pi's own built-in slash commands.** They do not exist in `pi --mode rpc`; there is nothing to
+  call. The extension's own commands work.
+- **`/login`.** Its OAuth flow has no rpc equivalent. Log in once with `pi` and the rest follows.
+
+## Transport
+
+- [x] Loopback by default. `--host` binds elsewhere, and refuses `--no-auth` when it does.
+      `test/web.test.ts`: *--no-auth is refused when the front end is put on the network*.
+- [x] A name you put in front of this — a reverse proxy, a hostname on your own network — is named
+      with `--allow-host`, nothing else is accepted under it, and the flag is in `--help`: a flag
+      that relaxes a security check and is not documented is a flag nobody can audit.
+      `test/web.test.ts`: *--allow-host admits the name you put in front of it, and no other*.
+- [x] A `--port` that is not a port is refused out loud rather than served somewhere else.
+      `test/web.test.ts`: *a --port that is not a number is refused rather than quietly served
+      somewhere else*.
+- [x] **Every route keeps its own guards, the escape hatch included.** `/rpc` carries anything in
+      pi's protocol this front end has not grown a button for, and refuses the commands that do have
+      a route here — reaching pi through it skipped the mid-turn refusal, the "one of this project's
+      sessions" check, and the reset the attached browsers are owed when a session is swapped. It
+      also refuses `new_session` and `clone`, which replace that session with no route to do the
+      resetting: opening a fresh session is `/switch_session`-shaped work.
+      `test/web.test.ts`: *the escape hatch cannot be used to skip a route's own guards*.
+- [x] The routes that only read are only read from: `/state`, `/history` and `/stats` answer GET and
+      nothing else. `test/web.test.ts`: *the routes that only read are only read from*.
+- [x] A request another site started is refused on every route, whatever cookie the browser
+      attached. `test/web.test.ts`: *a request another site started is refused*.
+- [x] One address that does not change between launches, and a device is added by pointing its
+      camera at a QR — with the six digits as the fallback, never a curl command.
+      `test/web.test.ts`: *the token outlives the process*, *a phone gets in with the six-digit
+      code*. `test/web-page.test.ts`: *adding a device shows a code and something to point a camera
+      at*, *the QR encoder still produces the matrix a scanner was shown*. A guess spends one of
+      twenty tries, so a browser that is already signed in is recognised as signed in first —
+      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] Pairing survives an upgrade: the token is a file outside the package, so a device stays signed
+      in across restarts and new versions. `test/web.test.ts`: *the token outlives the process*.
+- [x] Events are incremental. The backlog a late-joining browser replays is bounded.
+- [x] Events carry no credential and no oversized tool payload; the image bytes a message already
+      contains travel with it, and the page renders them rather than fetching them. The page itself
+      is handed the token — in the cookie, and in the URL on a first visit — and nothing else is. The
+      one event that could have carried a credential was pi's stderr, broadcast when it exits to say
+      why: a provider that refuses to authenticate prints the key it was refused with, so that tail
+      is capped and redacted before it leaves this process. The terminal that started the session
+      still has the whole of it.
+      `test/web.test.ts`: *a credential in pi's dying words does not reach the page*.

package/examples/README.md

@@ -0,0 +1,18 @@
+# Examples
+
+## mcp-notify-server.mjs — an MCP server that pushes into pi-loops
+
+An MCP server in Node with no dependencies, small enough to read in one sitting.
+The server registers one tool (`demo_status`) and pushes a `notifications/pi/demo/heartbeat`
+event every 10 seconds. Each push carries `_meta.pi_dedup_key` (unique per beat, so nothing is
+deduplicated away) and `_meta.pi_summary` (the text the audit, the panel and — with
+`inject_summary` — the chat will show).
+
+```sh
+cp examples/mcp.toml ~/.pi/agent/loops/mcp.toml    # or merge the [[server]] block
+pi                                                  # then: /triggers sources
+```
+
+Without an `inject_*` flag each push is evaluated by the dynamic-rule sub-agent against your
+`/new-trigger` rules; with `inject_summary = true` the summary lands in the chat directly;
+with `inject_and_run = true` the agent also reacts to it. See [docs/mcp.md](../docs/mcp.md).

package/examples/mcp-notify-server.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Minimal MCP stdio server that pushes notifications into pi-loops' trigger runtime.
+// Node built-ins only. JSON-RPC 2.0, one message per line. Registers one tool and emits a
+// `notifications/pi/demo/heartbeat` event every 10 seconds; each carries a unique
+// `_meta.pi_dedup_key` (so every beat counts as a distinct trigger) and a human-readable
+// `_meta.pi_summary` (what the audit and the chat see).
+import readline from "node:readline";
+
+const send = (m) => process.stdout.write(`${JSON.stringify(m)}\n`);
+let beats = 0;
+const rl = readline.createInterface({ input: process.stdin });
+rl.on("line", (line) => {
+	let msg;
+	try {
+		msg = JSON.parse(line);
+	} catch {
+		return;
+	}
+	if (msg.method === "initialize") {
+		send({ jsonrpc: "2.0", id: msg.id, result: { protocolVersion: "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "pi-loops-notify-demo", version: "0.1.0" } } });
+	} else if (msg.method === "notifications/initialized") {
+		setInterval(() => {
+			beats++;
+			send({ jsonrpc: "2.0", method: "notifications/pi/demo/heartbeat", params: { _meta: { pi_dedup_key: `beat-${process.pid}-${beats}`, pi_summary: `demo heartbeat #${beats} at ${new Date().toISOString()}` } } });
+		}, 10_000).unref?.();
+	} else if (msg.method === "tools/list") {
+		send({ jsonrpc: "2.0", id: msg.id, result: { tools: [{ name: "demo_status", description: "How many heartbeats this demo server has pushed", inputSchema: { type: "object", properties: {} } }] } });
+	} else if (msg.method === "tools/call") {
+		send({ jsonrpc: "2.0", id: msg.id, result: { content: [{ type: "text", text: `pushed ${beats} heartbeat(s) so far` }], isError: false } });
+	} else if (msg.method === "ping") {
+		send({ jsonrpc: "2.0", id: msg.id, result: {} });
+	} else if (msg.id !== undefined) {
+		send({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `unsupported method ${msg.method}` } });
+	}
+});

package/examples/mcp.toml

@@ -0,0 +1,8 @@
+# Copy into ~/.pi/agent/loops/mcp.toml (or <project>/.pi/mcp.toml in a trusted project).
+# `args` is relative to the directory pi runs in; use an absolute path to make it work anywhere.
+[[server]]
+name = "notify-demo"
+command = "node"
+args = ["examples/mcp-notify-server.mjs"]
+# inject_summary = true      # push the summary straight into the chat, no model call
+# inject_and_run = true      # push it and run one model turn on it