@alphacoder-v0/pi-loops 0.17.3

package/docs/cli.md

@@ -0,0 +1,252 @@
+# The `pi-loops` command line
+
+`pi-loops` starts a session. With no arguments it opens the browser front end when you are at a
+local terminal, and pi itself when you are not — over ssh, or with no terminal at all, where a
+browser on this machine would help nobody. `--web` and `--tui` say which when the guess is wrong.
+
+```
+pi-loops                             # start a session, in whichever window makes sense here
+pi-loops --tui                       # the terminal one
+pi-loops --web --port 4200           # the browser one, on a port you chose
+pi-loops --model anthropic/claude-opus-5 -e .   # anything it does not recognise goes to pi
+```
+
+Both are complete pi sessions: the browser one runs `pi --mode rpc` behind a page ([src/web.mjs](../src/web.mjs)),
+so the session file, `--resume`, 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 mode, and
+`/login`, whose OAuth flow has no equivalent — log in once with `pi` and the rest follows.
+
+Ctrl-C in the terminal you started it from ends the session the way `/quit` does: pi is asked to
+shut down rather than killed, so it still hands the clock to a headless host when there are loops,
+rules or MCP pushes to keep running, and the line saying so is printed before the window closes. That
+line is pi's own when it arrives in time — pi addresses it to the window rather than to the terminal,
+so when it does not, the front end reads `host.json` itself and says either `automation handed to a
+background host (pid N); pi-loops host status | stop` or `no background host started; automation is
+not running — see <loops dir>/host.log`.
+
+### The address
+
+Always `http://127.0.0.1:4173/`. Bookmark it. The port is fixed rather than "whatever was free",
+and the token that guards it lives in `~/.pi/agent/loops/web-token` (mode 0600) rather than being
+made fresh every launch — so the address is the same one tomorrow, and the first visit leaves a
+cookie that means you never see the token again. `--port <n>` moves it if 4173 is spoken for.
+
+There is a token at all because anything that reaches this server gets your whole session, and
+"anything" includes a website you have open in another tab: it cannot read the answers, but
+without a check it could still tell your agent what to do. The cookie is `SameSite=Strict`, which
+is a browser's promise not to send it on anything another site started, so the cost of this to you
+is one visit and then nothing.
+
+Running `pi-loops` a second time while one is up does not fail on the busy port — it opens the
+window that is already there and leaves.
+
+### From a phone
+
+The front end binds loopback, which a phone cannot reach. Two ways round it, and the first is
+better:
+
+**Tailscale.** Leave the server where it is and put Tailscale in front:
+
+```
+tailscale serve --bg 4173
+```
+
+Your phone then opens `https://<machine>.<tailnet>.ts.net/` — TLS terminated on the tailnet, only
+your own devices, and this server still bound to 127.0.0.1. It arrives here looking local and
+carrying the tailnet name as its `Host`, which is accepted for that reason.
+
+**The local network.** `pi-loops --host 0.0.0.0` binds every interface and prints the addresses a
+phone on the same wifi can use. Anything that can open the port is then talking to your session, so
+the token is not optional here — `--no-auth` is refused outright in this mode.
+
+`tailscale funnel` is the same shape and puts it on the open internet; the token is what stands
+between that and anyone, so `--no-auth` refuses to serve anything but loopback no matter which
+route a request took to arrive.
+
+Either way the phone has to get in once, and the token is 32 hex characters, which is fine to click
+and miserable to type. So: press **add device** in the browser you are already signed in on. It
+shows a **QR code** — point the phone at it and it is in, having typed nothing — and the same six
+digits underneath for when a camera is not the thing you want to use. The terminal prints a code at
+startup too.
+
+The QR encodes the address *this browser reached the server on*, which under `tailscale serve` is
+the tailnet name and is the one that works from anywhere on your tailnet. If the window you press it
+in is on `127.0.0.1`, there is no address to put in a QR that would work from a phone, and it says
+so instead of showing you one that does not.
+
+A code is good for one use and lasts ten minutes; twenty wrong guesses disable it until you ask
+for another.
+
+On a network you do not own, remember that `--host` is plain http: the cookie it hands out carries
+a token that outlives the process, and anyone on the wire can read it. That is the case
+`tailscale serve` exists for, and the startup output says so.
+
+Add it to the home screen and it opens without browser chrome: there is a web app manifest, and no
+service worker — nothing here is worth caching, and a stale copy of a live front end is worse than
+no copy.
+
+### Dropping the token
+
+`pi-loops --no-auth` drops the token entirely: no cookie, no query string, nothing to carry, and
+anything on this machine that can open port 4173 has your session. What is left is the check that
+the request did not come from another site — a browser tells the truth about that, and it is what
+keeps a page on `http://localhost:5173` from posting into your agent — but any *program* running as
+any user on this machine is then in. It is the right trade on a machine only you use, and the wrong
+one on a shared host.
+
+A browser that has never been here (a different one, or after clearing cookies) gets a page saying
+so. Start a session from a terminal on this machine and it will open a window that works from then
+on, or use the `?token=…` address the terminal printed.
+
+### It starts a session; it does not attach to one
+
+The browser front end starts its own `pi --mode rpc`. It does not join a pi you already have open
+in a terminal — two front ends driving one agent is not something pi offers, and pretending
+otherwise would mean two windows disagreeing about whose turn it is.
+
+Picking up where you left off is a different thing, and pi already has it. The flags reach pi
+unchanged, so:
+
+```
+pi-loops --continue                  # the newest session in this directory, in the browser
+pi-loops --resume                    # pick one
+pi-loops --session <id-or-path>      # a particular one
+```
+
+That also means you can hand a session between windows: quit the terminal one, `pi-loops --continue`,
+and carry on in the browser with the same transcript.
+
+### Starting over, without leaving the window
+
+The context is finished with far more often than the window is, so the things you do between turns
+are in the page rather than in the terminal that launched it:
+
+| | |
+|---|---|
+| **clear** / `/clear`, `/new` | start a new session here |
+| **resume** / `/resume` | go back to an earlier session in this project |
+| **compact** / `/compact <what to keep>` | summarise what is there and carry on |
+
+Nothing is deleted by any of them. The session you leave is a file on disk, and **resume** lists
+this project's sessions newest first, each labelled by what was said in it rather than by a
+filename. Compaction reports what the context was, what it became, and what the summary cost.
+
+Underneath, **clear** and **resume** are pi's `switch_session`: the session is replaced inside the
+process that is already running, so the model, the MCP connections and the extensions are the same
+ones, rebuilt against the new session. That is what `/new` and `/resume` do in the terminal, and
+automation follows it the same way — the scheduler stops and starts with the session rather than
+handing the clock to the headless host, and a scheduled run the swap interrupts gives its slot back
+and fires again on the next tick.
+
+One thing the front end adds on top of the swap: **resume** puts the session back on the model it
+was last using. pi re-resolves the launch command line's `--model` on every swap — and the launcher
+supplies one from the model you last chose ([configuration.md](configuration.md#what-is-remembered-between-sessions))
+— so without this, going back to a conversation had with one model landed it on a different one. If
+the model it used is not available any more (credentials gone), the session stays on the one it has
+and the terminal says which model it could not go back to.
+
+Both are refused while a turn is running, because the swap would abort it: stop the turn first. A
+session started this way is named by the front end rather than by pi, which is invisible everywhere
+except that its filename does not contain its session id — pi and pi-loops both identify a session
+by the id in its header.
+
+## Getting the command onto your PATH
+
+`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 — and
+putting itself there is the one thing it cannot do for itself. Run it from inside pi, where the
+extension is already loaded:
+
+```text
+/pi-loops install-launcher
+```
+
+or from the directory pi installed the package into — `~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops`
+for a `pi install npm:` package, `~/.pi/agent/git/<host>/<owner>/<repo>` for a `pi install git:` one:
+
+```bash
+node src/cli-entry.mjs install-launcher
+node src/cli-entry.mjs install-launcher --dir ~/bin
+```
+
+It writes a two-line `sh` script that names the node you ran it with and the package it lives in —
+a launcher rather than a symlink, so it keeps working if either moves for the other's reason.
+
+## Upgrading
+
+```bash
+pi-loops upgrade                     # install the newest release
+pi-loops upgrade --check             # say whether there is one, and stop
+```
+
+It reads release tags from the repository this copy came from (`repository.url` in its
+`package.json`, so a fork upgrades from the fork), takes the highest `vN.N.N` — comparing
+numerically, so `v0.10.0` beats `v0.9.0` — and runs `pi install` for it. Release candidates and
+branch-shaped tags are ignored: those are not things to move someone onto without being asked.
+
+`pi update --extensions` does something different and both are useful: it reconciles every package
+to the ref already pinned in your settings, which is how you repair a clone, not how you take a new
+version.
+
+## The tools
+
+The rest of the command line does not need a pi session and has no build step; it resolves pi's
+packages the way the headless host does. `PI_LOOPS_DIR` selects the loops directory, as everywhere.
+
+```
+pi-loops sessions [--all] [--limit <n>]
+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]
+pi-loops host status | abort <run-id|trace-id> | stop
+```
+
+## sessions, inspect
+
+`sessions` lists the ids `export --session` accepts, newest first — without it an unknown id was
+the only error you could get. `inspect` prints an archive's schedules, prompts and rules without
+writing anything, which is what you want before restoring on a machine you care about.
+
+## export
+
+Bundles a session's transcript with the automation that session created — its cron jobs, trigger
+rules and loop state — into one `.pisession` archive.
+
+With no `--session`, the newest session recorded for `--cwd` (default: the current directory) is
+taken. `--session` accepts a full id or a unique prefix. `--exclude-triggers` drops every automation
+sidecar.
+
+```
+pi-loops export --session 01a084a0 --output ~/backups/api.pisession
+```
+
+## import
+
+Restores an archive into `--cwd` (default: the current directory), rewriting ids, project and
+machine so the automation runs where it landed.
+
+Imported automation stays disabled unless `--activate-triggers=on`; `ask` prompts on a terminal.
+Importing the same archive twice adds nothing the second time.
+
+## host
+
+The headless host has no chat, so `host status` is how you see what it is doing while no pi is
+open: the loop runs and trigger checks in flight, what is enabled, the inbox count, and each MCP
+server's state.
+
+```
+$ pi-loops host status
+background host
+  pid 2949521 on box, started 2026-09-09T13:33:16.652+08:00, model openai-codex/gpt-5.5
+  owns the clock · 1/1 loop(s), 0/0 rule(s) enabled · inbox: 0 new
+  running nightly (run-97ffb250) since 2026-09-09T13:34:16.676+08:00: check the repo issues
+```
+
+The stamps carry the offset of the machine the host runs on ([loops.md](loops.md#time-and-which-clock-it-is));
+these are a `+08:00` machine's.
+
+`host abort <id>` interrupts one run or trigger check (the shortened ids the status prints are
+accepted). `host stop` ends the host; the next pi to open would have taken the clock back anyway.
+
+The channel is a unix socket at `host.sock` in the loops directory, created 0600, and it is
+read-mostly on purpose: a host you could prompt would be a second chat.

package/docs/configuration.md

@@ -0,0 +1,110 @@
+# Configuration
+
+Everything lives under `~/.pi/agent/loops/` (override: `PI_LOOPS_DIR`).
+
+| File | Purpose |
+|---|---|
+| `config.toml` | `allow_project_hooks`, `[triggers] poll_interval_secs = 600` / `run_timeout_secs = 900`, `[cron] catch_up = true` / `max_concurrent_runs = 3`, `[hooks] mode = "sync"`, `[host] auto = true`, `[limits] daily_budget_usd = 0`, `[danger] allow = []` |
+| `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`), and `model` / `thinking` — the last ones you chose in the browser front end, applied to the next session that does not say otherwise |
+| `jobs.json`, `triggers.json` | cron jobs and trigger rules (machine-global, each with a `cwd`) |
+| `state/<id>.md` | loop notes; plain Markdown, editable |
+| `inbox.jsonl` | the inbox (past 1 MB the oldest triaged findings are dropped; nothing still new) |
+| `runs.jsonl`, `triggers-audit.jsonl` | run log (halved past 1 MB) and trigger audit (2 MB) |
+| `spend.json` | per-day totals of what rotation dropped from the run log, so a daily budget still counts it |
+| `sessions/<job-id>/`, `sessions/triggers-<project>-<hash>/` | sub-agent transcripts (20 per job, 40 per project's checks; the hash of the project's path keeps two projects named alike apart) |
+| `scheduler.<host>.json` | timer owner on this host: pid, heartbeat |
+| `presence/` | one file per live pi process: pid, session, cwd (who acts for which project) |
+| `host.json`, `host.log` | the headless host that keeps the clock while no pi is open: pid, and its log |
+| `polls.json` | last dynamic check per project (shared, so a hand-over never double-checks) |
+| `dedup.json` | machine-wide trigger dedup window (5 minutes) |
+| `web-token` | the browser front end's token, mode 0600. It lives in a file rather than being made per launch so the address stays the same one and a signed-in device stays signed in across restarts and upgrades. Delete it to sign every device out |
+
+Project-level: `<project>/.pi/mcp.toml` (trusted projects only) and `<project>/.pi/hooks.toml`
+(when allowed).
+An invalid `[triggers] poll_interval_secs` (or `--trigger-poll-secs`) is reported at startup
+and ignored.
+
+## `[cron] max_concurrent_runs`
+
+How many **sub-agents** this pi process may have in flight at once — not how many loop runs. Loop
+runs, dynamic-trigger checks and trigger actions all draw on the same counter, because they are the
+same thing to the machine: an in-process pi session, on your model, on your bill. With
+`max_concurrent_runs = 3` you get at most three of them together, in any mix.
+
+The count is per process. Two pi windows are two processes and two counters; nothing is
+coordinated across them, because what the cap protects — this process's memory, sockets and
+in-flight requests — is not shared either.
+
+What a refusal means differs by pipeline, on purpose:
+
+- a **loop run** is deferred, not skipped: the tick stays owed, `/cron list` shows
+  `deferred: N sub-agent(s) already in flight`, and the next tick tries again;
+- an **MCP push** is held (up to 32) and retried on the next tick, because no server sends the same
+  event twice;
+- a **periodic trigger check** is dropped, because the next poll asks the same question of a world
+  that has moved on.
+
+Two kinds of sub-agent **count against the cap but are never refused a slot**: `/cron run`, and the
+`/goal` evaluator. Both are things you asked for directly — the evaluator runs after every turn of a
+session that has a goal, one at a time, and a busy machine quietly declining to evaluate would be
+indistinguishable from a goal that was never set. They can therefore take the total past the limit,
+which is why the in-flight count is reported against it (`4 of 3 sub-agent slot(s) in use`) rather than assumed
+to be under it. If you have a goal running and want headroom for it, size the setting one higher.
+
+## Flags and environment
+
+| | |
+|---|---|
+| `--trigger-poll-secs <n>` | dynamic trigger poll interval for this run |
+| `PI_LOOPS_DIR` | relocate the data directory |
+| `PI_WEB_TOKEN` | use this instead of the token in `web-token`. Letters, digits, `-` and `_`, at least 8 of them: it is substituted into a JavaScript string in the page, and a quote there would end the string early |
+| `PI_ALLOW_PROJECT_HOOKS=1` | allow project hooks. `true` works too; anything else is off |
+| `PI_LOOPS_HOST=1` | let a `pi -p` run host the timer for as long as it lives (the headless host below is the normal answer) |
+| `PI_LOOPS_DEBUG=1` | add a line per provider retry, compaction and tool call of a sub-agent run to `logs/pi-<pid>.log` |
+| `PI_BIN` | the pi executable to start, when it is not the `pi` on your `PATH` |
+
+## What is remembered between sessions
+
+A session opens on pi's default model, so choosing the same one every morning was the first thing
+the browser front end asked of anybody. Changing the model or the thinking level there records it in
+`ui.json`, and `pi-loops` applies it when it starts the next session — the terminal window too,
+since the launcher is what applies it.
+
+It is not applied when you said which model yourself (`pi-loops --model …`), and not when the
+session already has one: `--continue`, `--resume`, `--session` and `--session-id` keep the model
+their conversation was had with. Delete the keys from `ui.json` to go back to pi's default.
+
+A `--model` — yours or the remembered one — lasts as long as the process, not as long as the
+session: pi re-resolves it every time the session inside the process is replaced. So **resume** in
+the browser front end re-applies the model the session it is going back to was last using, which is
+what a fresh `pi --resume` would have done.
+
+## The browser front end
+
+`pi-loops` takes these for itself and passes everything else to pi. Full explanation in
+[cli.md](cli.md); this is the list.
+
+| | |
+|---|---|
+| `--web` / `--tui` | which window, when the guess is wrong |
+| `--port <n>` | default 4173, fixed on purpose so the address is worth bookmarking |
+| `--host <addr>` | bind somewhere other than loopback, so a phone on the same network can reach it. Prints the addresses it can be reached on, and says that they are unencrypted |
+| `--allow-host <name,…>` | accept these values in the `Host` header, for a reverse proxy in front. A name resolved by public DNS puts the token back in charge of keeping strangers out |
+| `--no-auth` | no token and no cookie. Loopback only, whatever route a request took, and refused outright with `--host` |
+| `--no-open` | do not open a browser |
+| `--loops-dir <dir>` | the same thing `PI_LOOPS_DIR` does |
+
+Tailnet names (`*.ts.net`) are accepted from a tailnet connection without `--allow-host`, which is
+what makes `tailscale serve --bg 4173` work with the server still on loopback.
+
+## Per-job options (`/cron add`)
+
+`--name`, `--cwd <dir>`, `--model provider/id`, `--thinking <level>`, `--tools a,b`
+(allowlist for the sub-agent), `--timeout 20m` (default 15m), `--catchup` / `--no-catchup` (default: loops on, plain jobs off), `--stateful` (or `--loop`),
+`--inject` (a plain job — the default, spelled out), `--verify`, `--checker-model provider/id`. Change model, thinking, timeout or name later with
+`/cron set <id> …` (`-` = follow the running session). Sub-agents run inside the interactive pi
+(pi's SDK) and share its live MCP servers, its `-e` extensions, system-prompt and skill flags, its
+model unless the job pins one, and the project's trust when they run in the same project.

package/docs/design.md

@@ -0,0 +1,155 @@
+# Design
+
+## What each piece is built out of
+
+pi-loops is a plain extension. Everything below is a public pi API doing a job the runtime does not
+do for you.
+
+| the job | what does it |
+|---|---|
+| a clock | `setInterval` started in `session_start`, cleared in `session_shutdown` |
+| a scheduled job that lands in your chat | `pi.sendUserMessage` (follow-up queue when busy), `[Trigger <id>] ` prefix |
+| a scheduled job that must not touch your chat | an in-process `AgentSession` from pi's SDK (`src/sdk-runner.ts`): fresh context, own transcript, the parent's tools, MCP clients, extensions, model and trust |
+| state that outlives a session | `jobs.json`, `triggers.json`, `state/<id>.md` under `~/.pi/agent/loops` |
+| a record of who changed what | `pi.appendEntry` for cron control operations; `triggers-audit.jsonl` for trigger runs |
+| something to look at | transcript cards via `pi.appendEntry` + an entry renderer; a widget above the editor; a footer badge via `ctx.ui.setStatus` |
+| a decision only a person should make | `ctx.ui.confirm` inside the tool |
+| notifications from outside | `src/mcp.ts`, a client that consumes them |
+| a way to react to the session's own events | `src/hooks.ts` |
+| a session you can carry to another machine | `src/archive.ts` |
+
+## The decisions, and what each costs
+
+The premise is that **"pi was restarted" is the normal case**. Automation that dies with the window
+it was configured in is automation you cannot rely on, so jobs and rules live on disk for the whole
+machine. Everything here follows from that, and each one has a price.
+
+1. **Machine-global jobs and rules, each carrying a `cwd` and a `host`.** `/cron` and
+   `/triggers rules` show the current project by default, and say how many are elsewhere. A plain
+   (inject) job belongs to the session that created it: listed as `[dormant …]` while that session
+   is not open, parked as disabled once the session no longer exists (`/cron gc` removes it). A loop
+   whose `cwd` disappeared waits half an hour — a mount can be late at boot — and is disabled after
+   that. Jobs and rules stamped with another host (a shared `$HOME`) are ignored here and listed
+   with whose they are; leader election is per host.
+
+   The cost: a list has to be scoped, and a job you cannot see reads as a job that is gone. Hence
+   the counts, the markers, and `/cron all`.
+
+2. **Who runs what.** Every process ticks. Loops run in the machine leader
+   (`scheduler.<host>.json`, a pid and a heartbeat). A project's dynamic checks and push
+   evaluations run in a pi that is *open in that project* — preferring the session that created the
+   rules, lowest pid otherwise (`presence/`) — so a promotion lands in the conversation it belongs
+   to. Only a project with no pi open falls to the leader, and its results go to the inbox
+   (`redirected`). The poll interval is enforced machine-wide (`polls.json`), so a hand-over never
+   double-checks.
+
+3. **Model and thinking level are recorded when a job is created** and editable afterwards
+   (`/cron set`, `/triggers set`; `--model -` follows the running session). A loop that was set up
+   against a capable model does not quietly start running on whatever the newest session happens to
+   be using.
+
+4. **MCP pushes.** A push that injects into the chat reaches every window that has the server. A
+   push evaluated against rules is evaluated once per project, by that project's owner. Sub-agents
+   ignore pushes; anything that reaches hop ≥ 1 is audited as `cycle_suppressed`.
+
+5. **Sub-agents are sessions, not processes** (`createAgentSession`). They share the parent's live
+   MCP client instances — the browser tab or database session opened in the chat is the one a loop
+   sees — its `-e` extensions, system prompt and skill flags, its model unless the job pins one, the
+   project's trust when the run is in a project this session or an earlier `/trust` decision
+   trusted (never by default), and the parent session's id, so plain jobs they schedule bind to it.
+   The parent's extensions get their `session_start` / `session_shutdown` in every sub-session.
+   Each run gets its own transcript file and a configurable cap (`[triggers] run_timeout_secs`,
+   per-rule `--timeout`). Nothing is re-spawned per run.
+
+   The cost: a sub-agent has no UI, so a tool that would ask for confirmation is denied
+   fail-closed there. Nobody can say yes, so the answer has to be no.
+
+6. **Catch-up.** A loop tick missed while no pi was running is fired once at startup, collapsed
+   rather than replayed (`[cron] catch_up = false` or `--no-catchup` turns it off). Plain jobs do
+   not catch up unless `--catchup`: they land in a conversation, and a conversation that opens to
+   four hours of backfill is worse than one that opens to nothing. A run that died with its process
+   is retried. `[cron] max_concurrent_runs` (3) bounds the burst.
+
+7. **Audit is both a file and part of the session.** A machine-wide JSONL
+   (`triggers-audit.jsonl`, rotated at 2 MB) *and* session custom entries (`trigger`,
+   `trigger_result`, `trigger_promotion`), so it resumes and exports with the session it belongs
+   to. `/triggers audit` shows this project's rows (`--all` for every project).
+
+8. **Hooks are awaited inline**, so a hook that is slow is visibly slow rather than silently
+   racing the turn that triggered it. `[hooks] mode = "async"` queues them off the turn instead.
+
+9. **A promotion that arrives while the agent is busy** goes to pi's follow-up queue and runs a
+   turn after the current one; when the agent is idle it is inserted without a model call.
+
+10. **Nobody around.** When the last interactive pi on the machine quits with loops, rules or MCP
+    servers configured, it starts a headless host (`src/host.ts`, a plain `node` process using the
+    same stores, the same in-process runner and its own MCP clients) that keeps the clock: loops,
+    trigger checks for every project, pushes, catch-up. Chat-bound output goes to the inbox. The
+    first interactive pi to open takes the clock back — its scheduler preempts a `host` leader —
+    and the host exits. `/cron host [start|stop]`, `[host] auto = false` to opt out, `host.log` for
+    its output.
+
+    What triggers it is pi shutting a session down cleanly with reason `quit`: `/quit` in a terminal,
+    or SIGTERM/SIGHUP, which are the signals pi handles. Nothing else does — so the browser front end
+    starts its pi in a process group of its own and turns a Ctrl-C into that SIGTERM itself
+    (`src/web.mjs`). A pi that shares the terminal's group is killed by the group's SIGINT, which pi
+    has no handler for, and the hand-off never happens.
+
+    The cost: nothing restarts it after a machine reboot until a pi opens. It is a hand-off between
+    processes, not a system service, and installing one would mean asking for privileges this does
+    not otherwise need.
+
+11. **Bounded everywhere, and no expiry.** Loop state ≤ 2000 characters, a finding ≤ 500, at most
+    16 per run, prompts ≤ 8 KB. A job disappears when you remove it and not before.
+
+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
+    trigger runtime, so nothing nests.
+
+13. **Stdio MCP servers reconnect** with backoff (20 attempts by default), each distinct error
+    reported once rather than on every retry.
+
+14. **A bill, and a cap on it.** A headless host can run for days, so cost cannot be something you
+    discover at the end of the month: `[limits] daily_budget_usd` gates every dispatch, `/cron cost`
+    adds up the run log, and what log rotation drops is folded into `spend.json` first so the cap
+    does not quietly stop capping. A run stopped by the budget is recorded as aborted rather than
+    failed — the slot is still owed and the failure streak does not advance. Diagnostics go to
+    `logs/pi-<pid>.log` rather than only to a chat notification that a new session erases.
+
+## Where the browser front end came from
+
+pi owns the `pi` command and its terminal, so a second front end cannot replace the first one. It
+goes through the door pi already provides: `pi --mode rpc` — pi with no terminal UI, commands in
+and events out as JSON lines — with [src/web.mjs](../src/web.mjs), a browser front end in one
+dependency-free file, passing that protocol through to a page. The session is a real pi session,
+and `pi --resume` picks it up afterwards. What only the process knows — which MCP servers connected,
+what they exposed, the active tools, who owns the clock — reaches the page as the
+`pi_loops_snapshot` session entry.
+
+`pi-loops` with no arguments starts a session and picks the window: the browser at a local
+terminal, pi itself over ssh or with no terminal at all, because a browser on the far machine helps
+nobody. `--web` and `--tui` say which when the guess is wrong.
+
+Two things stay in the terminal. `/login` is one: OAuth has no rpc command, so a provider is logged
+in once with `pi` and the browser front end started afterwards. pi's built-in slash commands are
+the other — they do not exist in rpc mode, and the front end implements the ones that matter (cost,
+find, undo, save, compact, model, thinking, clear, resume) from rpc primitives rather than
+pretending. What the page owes you is kept as a gate rather than a wish list in
+[web-ui-parity.md](web-ui-parity.md).
+
+Reaching that page from a phone is solved without putting a broker in the middle: `tailscale serve`
+terminates TLS on your tailnet and proxies to this server on loopback, so the page is on your phone
+without anything of yours passing through a third party, and `--host` does the same over a local
+network for people who would rather not run a tailnet. What both need is a way in that a phone can
+manage — the pairing code and the QR ([cli.md](cli.md)). A phone on neither network is the case
+this does not cover; that one would need a relay.
+
+While nobody is at the terminal, the host's control channel is what answers "what is it doing":
+`pi-loops host status|abort|stop` ([cli.md](cli.md)).
+
+## What this is not
+
+An agent. Writing code, reading the web, managing skills — those are pi's, and this does not
+duplicate them. What it decides is *when* work happens, *where* it runs, and *what context it
+carries*; the work itself is done by the agent you already have.

package/docs/goal.md

@@ -0,0 +1,59 @@
+# Goals: holding a session to a stop condition
+
+`/goal` is a stop condition the session is held to, and the only mechanism
+here that asks "am I done yet". Cron jobs, loops and triggers all run on a clock or an event; a goal
+runs on a judgement.
+
+```
+/goal the test suite passes and the changes are committed
+```
+
+After every settled turn an evaluator — a model call with no tools, reading only a bounded
+transcript of the whole conversation on the active branch — answers one question: is the condition
+satisfied? Evidence from an earlier turn counts: the evaluator sees the session, not just the run
+that happened to end. It must reply in a fixed shape,
+quoting the transcript:
+
+```json
+{"ok": true,  "reason": "npm test reported 0 failures"}
+{"ok": false, "reason": "3 tests still fail in parser.test.ts"}
+```
+
+`ok: false` sends the agent back to work with what is missing, as a normal user turn. `ok: true`
+stops and shows the evidence. Missing evidence is not success: an evaluator with nothing to point at
+is told to answer `{"ok": false, "reason": "insufficient evidence in transcript"}`.
+
+## What bounds it
+
+| Guard | Behaviour |
+|---|---|
+| Continuations | At most 8, then the goal is `budget_limited` and pauses |
+| Evaluator failure | Pauses with the reason; it never loops on an evaluator that cannot decide |
+| Transcript | 40 000 characters, truncated from the front so the newest evidence always survives |
+| Tools | None. The evaluator reads, it does not act |
+| Interruption | A turn you aborted is not judged, and Esc during an evaluation stops it |
+| Its own timeout | 2 minutes; it is one read, not a piece of work |
+
+`/goal resume` after a budget limit starts the allowance again. `pause`, `resume` and `clear` are
+matched as whole words, so `/goal clear the type errors first` sets that as the condition rather
+than dropping the goal.
+
+## Commands
+
+```
+/goal <condition>     hold this session to a condition (then send a prompt to begin)
+/goal                 show the condition, the status, and what the evaluator last said
+/goal pause           stop evaluating, keep the condition
+/goal resume          start evaluating again
+/goal clear           drop the goal
+```
+
+## Where it lives
+
+Each state change is appended to the session as a `goal_state` entry, so `--resume` picks the goal
+up where it left off. The status line shows `goal: <status>`; the
+statuses are `pursuing`, `paused`, `achieved`, `budget_limited` and `cleared` (what `/goal clear`
+leaves behind).
+
+The evaluator runs as a sub-agent with the session's model, so it is billed like any other run and
+its transcript is kept with them.