@alphacoder-v0/pi-loops 0.22.7 → 0.24.0

package/docs/design.md

@@ -8,8 +8,8 @@ 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 |
+| a scheduled job that lands in your chat | a row in `requests/<session>.jsonl`, handed to `pi.sendUserMessage` by the window holding the session once the agent is idle, `[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, and the tools, MCP clients, extensions and model of the process that runs it (pi-loops, for loops and checks) |
 | 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` |
@@ -27,46 +27,77 @@ machine. Everything here follows from that, and each one has a price.
 1. **Machine-global jobs and rules, each carrying a `cwd`.** `/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 — its result is a message in that
-   conversation — and everything that lists it agrees with dispatch about that: another session
-   shows it as `[session <id> — resume it to run]` with no next run, `cron_list` says the same to
-   the model, `/cron run` refuses it. Asleep is not broken. It is parked as disabled only once its
-   session's file has been deleted (`/cron gc` removes it). A loop
+   conversation — and everything that lists it agrees with dispatch about that. While no window
+   holds the conversation pi-loops fires it there, holding the conversation for that one turn
+   (`[session <id> — in the background]`); when pi-loops is not running it is paused (`paused: <why>`), and for a
+   conversation whose file pi-loops never saw it is asleep (`[session <id> — resume it to run]`, no
+   next run, `/cron run` refuses).
+   Asleep is not broken. It is parked as disabled only once its session's file has been deleted
+   (`/cron gc` removes it). A conversation open in two windows is
+   held by one of them: a lease in `leases/<session>.json` names the holding instance, and it changes
+   hands when its holder releases it or that process is gone (its pid, or a recycled pid's start
+   time), and a window takes it from pi-loops at once; never on a timer.
+   The other window is a viewer and fires none of the conversation's plain jobs. A loop
    whose `cwd` disappeared waits half an hour — a mount can be late at boot — and is disabled after
    that.
 
    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.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.
+   the counts, the markers, and `/cron all`. And a holder that is alive but frozen (stopped in a
+   debugger, a wedged process) keeps its conversation's plain jobs waiting until it exits. The lease
+   does not expire on a timer on purpose: a timer cannot tell a frozen window from a suspended
+   laptop, and one is what used to move the clock away from a laptop that had only been asleep.
+   pi-loops writing into a closed conversation costs one race, stated: a person who opens the
+   conversation during the seconds pi-loops spends on a turn there takes it back at once and the
+   turn stops, but what pi-loops wrote meanwhile is on disk and not on that screen. Their next
+   entry is a sibling branch (a pi session is a tree, so nothing is lost), and the window says so;
+   the slot is owed, so that window then runs the job once more, and the conversation shows the
+   stopped attempt before the answer. A pi with the conversation open but without pi-loops in it is
+   guarded against only by pi-loops leaving a file someone else wrote in the last two minutes alone.
+   A held turn is a run like a loop's (a record, its own cost, a failure streak), and its extensions
+   stay loaded for that conversation's later turns: up to eight conversations, released after an
+   hour idle.
+
+2. **Who runs what.** One always-on process runs stateful loops, dynamic-rule checks and MCP push
+   evaluation for a loops directory. A window starts it when there is work to run, including the plain jobs and queued rule results of
+   closed conversations. Windows run only
+   the plain jobs for conversations whose leases they hold. Rule results go to the conversation
+   that created the rule, queued for its holder when needed; when no window holds it, pi-loops
+   appends the result to the conversation. A queued row pi-loops cannot run (an attended one, which
+   waits for a window) costs it no read of the conversation on a tick where the conversation,
+   `jobs.json` and the queue are as they were and no backoff has ended; it remembers the three at
+   the last "nothing to do" and reads again when one moves. The inbox gets a result only when the conversation cannot
+   be written; shell-created rules go to the inbox. During an upgrade, `presence/` is read only to accommodate
+   pi-loops 0.22 windows; pi-loops writes `scheduler.json` for those old windows to read.
+
+   The cost: loops pause while pi-loops cannot start, whereas they previously ran in an interactive pi.
+   A loop no longer shares a window's live MCP connections; it connects its own from `mcp.toml`
+   and the project. A pi-loops process that is alive but frozen blocks nothing: a window replaces it after three
+   failed probes and a heartbeat it stopped writing. After a reboot, nothing runs until a pi window opens, unless the person installed
+   a user-managed service (decision 21).
 
 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
+   (`/cron set`, `/triggers set`; `--model -` clears the pin: a loop then uses pi's default model, a
+   plain job its conversation's). 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
+   push evaluated against rules is evaluated once per project, by pi-loops. 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.
+5. **Sub-agents are sessions, not processes** (`createAgentSession`). They share the live MCP
+   clients, extensions and model of the process that runs them. For loops and checks that process
+   is pi-loops: a loop sees pi-loops' own MCP connections and pi's default model unless the job
+   pins one, not a window's browser tab, `-e` extensions or flags. A run reads a project's own
+   resources only when pi has saved a trust decision for that exact directory (never by default).
+   That process'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
+6. **Catch-up.** A loop tick missed while pi-loops was not running is fired once when pi-loops starts, 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
@@ -83,23 +114,38 @@ machine. Everything here follows from that, and each one has a price.
 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.
+10. **One always-on process per loops directory.** It is a `node` process recorded in
+    `host-service.json`, with output in `host.log`. A window starts it on session start, every
+    30-second tick, and immediately after a loop, rule or relevant MCP server is added, when there is
+    enabled work. It runs stateful loops, dynamic-rule checks and MCP pushes, and the plain jobs of
+    conversations no window holds (decision 1).
+    It does not exit when windows open or close. `/pi-loops status` shows its pid, version, start time,
+    work, held conversations and log. `/pi-loops stop` records a manual stop until `/pi-loops start`, or until `pi-loops` opens the
+    page and says that loops and rules resume;
+    `[host] auto = false` and `PI_LOOPS_HOST=off` prevent automatic starts. When pi-loops cannot start, it is retried after 1, 5 and 30 minutes. pi-loops does not catch an error and carry on from inside the
+    process, because its state after an uncaught error cannot be trusted. An uncaught exception is logged first, with the runs in
+    flight, then counted and the process exits; a record left naming a dead process (SIGKILL, OOM)
+    counts the same, and so does an eviction. Three of those within five minutes pause pi-loops,
+    and it stays paused until `/pi-loops start`; a job whose runs die with their process three
+    times in a row is parked with the reason. When pi-loops cannot run here at all, it exits with code 78, which a systemd unit configured as in [cli.md](cli.md#running-pi-loops-under-your-own-service-manager) does not restart. A
+    window replaces pi-loops (SIGTERM, then SIGKILL after 10 seconds) only after three unanswered
+    control-socket probes and a heartbeat pi-loops stopped writing; pi-loops still ticking
+    with a broken socket is reported, not killed, and a starting pi-loops process is never killed. A newer
+    window replaces an older pi-loops process and starts its own at once; an older window never replaces a newer
+    pi-loops process, nor starts an old one while the newer window that asked for the upgrade is open. Under bun
+    pi-loops runs on the `node` found on PATH; with none, loops pause and say why. During an
+    upgrade, pi-loops 0.22 windows stand by for loops; pi-loops writes `scheduler.json` for them to
+    read. Those windows still run their held conversation's plain jobs and must be restarted to pick
+    up the new behaviour. After a reboot nothing runs until a pi opens, or under a service manager configured by the user. The costs are decision 2's.
+
+    The claim on a job is a read-modify-write of `jobs.json` under `jobs.lock`, a directory lock
+    that is broken as stale after 10 seconds (`src/lock.ts`). It has no fencing token. A process
+    stopped (SIGSTOP, a debugger) for more than 10 seconds between reading a job as idle and
+    writing its claim, and long enough for another process to take the clock and claim the same
+    job, writes its claim over that one when it resumes, and the job runs twice. That is outside
+    the guarantee: it needs a stop inside a synchronous section that takes microseconds, and a
+    laptop that sleeps stops every process at once, so the resumed holder finishes its write before
+    any other process's timer fires.
 
 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, when a one-shot has fired, or
@@ -114,7 +160,7 @@ machine. Everything here follows from that, and each one has a price.
 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
+14. **A bill, and a cap on it.** pi-loops 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
@@ -151,8 +197,8 @@ machine. Everything here follows from that, and each one has a price.
 17. **The wizard is deterministic; one step is not.** Choosing a recipe, its autonomy level, the
     copy and the `/cron add` lines run with no model and end in a confirmation that shows exactly
     what will be created. The one thing a template cannot do — describe *this* project's tracker —
-    is handed to the running session with `sendUserMessage`, the way `/inbox claim` hands over a
-    finding: explore the remote, propose, confirm, write the file — and when that turn settles with
+    is a request addressed to the running session (`requests/<session>.jsonl`), handed to the agent
+    once it is idle, the way `/inbox claim` hands over a finding: explore the remote, propose, confirm, write the file — and when that turn settles with
     the file there, the wizard resumes by itself, so the command is typed once. `pi-loops recipe`
     in the terminal does the deterministic part only.
 
@@ -165,13 +211,14 @@ machine. Everything here follows from that, and each one has a price.
     protection on the remote) are the ones that hold.
 
 19. **One machine.** Until 0.19.0 every job and rule carried the hostname that created it, another
-    machine sharing the `$HOME` ignored it and listed it as `[other host]`, `/cron set --host`
-    re-homed it, and the leader file was named per host. None of it matched the way pi-loops is
+    machine sharing the `$HOME` ignored it and listed it as belonging to another machine, `/cron set --host`
+    re-homed it, and the leader file was named per machine. None of it matched the way pi-loops is
     used: pi runs on one machine, the loops run there, and a phone or a
     laptop reaches the browser front end over a tailnet (`tailscale serve`) without moving the
-    execution anywhere. So the concept is gone: no `host` on a job or a rule (a stamp an older
-    build left is dropped when the file is read), no `--host`, no marker, `scheduler.json` and
-    `next-runs.json` plain. "Host" now means one thing here, the headless process.
+    execution anywhere. So machine ownership fields are gone from jobs and rules (an old field is
+    dropped when the file is read). `--host`, the marker, `scheduler.json` and `next-runs.json` are
+    gone too. Host is the code’s name for the background process; user-facing text says
+    pi-loops or in the background.
 
     The cost: two machines syncing one `$HOME` both run every job. That is not supported, and it
     is said rather than half-handled.
@@ -197,9 +244,292 @@ machine. Everything here follows from that, and each one has a price.
     [../src/cli.ts](../src/cli.ts), beside the one function that renders the script, so it is
     testable without pi; the extension is the caller.
 
-    The cost: a write outside the loops directory, which the Non-invasive invariant now names as its
-    one exception, and a question on somebody's first start — an interruption this project otherwise
-    does not make.
+    The cost: a write outside the loops directory, which the Non-invasive invariant names as one of
+    its two exceptions, and a question on somebody's first start — an interruption this project
+    otherwise does not make.
+
+21. **The background process serves the one page.** pi-loops in the background owns the browser
+    page: `127.0.0.1:4173` for the default loops directory (`[page] port`), a free port for a moved
+    one, recorded in `host-service.json`. `pi-loops` with no arguments asks it over the control
+    socket (`page-open`) to open a conversation and answers the address and a one-shot open key,
+    then opens the browser and exits. Neither the token nor the key enters argv, which any account
+    on the machine can read in `/proc/<pid>/cmdline`: the background process writes the keyed
+    address into `pages/open/<random>.html` (0600, in a 0700 directory) and answers its path, the
+    browser is opened on that `file:` address, and the file sends it on. The file is removed when
+    the key is spent or after 60 seconds, whichever comes first, and every one left is removed
+    when the page starts. The cost: a process that runs as you can read the file in those 60
+    seconds, as it could read `web-token` itself. A browser confined by snap or flatpak cannot read
+    a file under a hidden directory, so for it the hand-off fails; the launcher also prints the
+    conversation's address with a second one-use key (10 minutes), and never the token, because a
+    terminal's scrollback, recordings and shared screens keep what it prints. It asks as soon as
+    the control socket is open: the conversation's pi starts while the page is still binding, and only
+    the answer, which carries the address, waits for the bind. A pairing code is
+    made only when asked for, by `pi-loops pair` or the page's add device button. Each
+    open conversation is one `pi --mode rpc` child of the background process under `/c/<session>/`
+    (`src/page-children.ts`), stopped after 15 idle minutes, six at most. What 4174 used to show is
+    the Background view of the same page, at `/background`.
+
+    The page keeps `web-token` and checks the Host header against DNS rebinding. The token never
+    travels in a cookie, because a cookie ignores ports: the browser sends it to every server on
+    127.0.0.1, so any local process that binds a port and gets one request from the browser would
+    hold the token. Every route that needs the token takes it from the `x-pi-web-token` header (or,
+    on a GET, `?token=`); a POST that carries it anywhere else is refused with 403 before its body is
+    read and before anything is written to `requests/`. The page keeps the token in memory. Three
+    addresses a browser fetches without that header — the event stream, a file, a preview — take a
+    key minted for that address at `POST /c/<session>/key`: 16 random bytes, bound to the
+    conversation and the kind, a file's key to its exact path and a preview's to its id, held in
+    memory (256 at most). A file or preview key opens one load within 60 seconds; an event-stream
+    key lasts 10 minutes, because an EventSource reconnects with the address it was given.
+
+    A reload does not need the open key or the pairing code again. The first visit (the open key,
+    the six digits, or the token itself) sets `pi_web_device`, a device id (`HttpOnly`,
+    `SameSite=Strict`, one year), records it in `web-devices.json` (0600, keyed by a hash of the
+    token, so a new token starts with no devices), and hands the page a device secret once, which
+    the page keeps in `localStorage`. A later load with a known device cookie gets the page without
+    the token or the secret in it, and the page trades the cookie and the secret, in the
+    `x-pi-web-device-secret` header, for the token at `POST /c/<session>/token`. A wrong secret is
+    403, and twenty of them forget the device. `localStorage` belongs to this origin, port included,
+    so a server on another port that receives the cookie fetches what has no token in it (the page and the
+    Background view) and nothing else. A browser paired before 0.24.0 pairs once more. 0.24.0 keeps
+    0.22.8's `web-token`, and 0.22.8 kept it in a `pi_web_token` cookie; any answer to a request that
+    still carries that cookie clears it (`Max-Age=0`), so the live token stops travelling to every
+    port. Abort, run, stop,
+    upgrade and ring (the doorbell: `request:<session>` or `lease:<session>`, answered before the
+    delivery runs) stay on the control socket.
+
+    A page child is a window: it holds its conversation's lease as a terminal in `rpc` mode, and
+    marks the lease `page: true`, with `turnSince` from `agent_start` until `agent_settled` (pi
+    retries, compacts and continues after `agent_end`) and while a compaction runs. A `tui` window takes a
+    conversation from an idle page child at once; while the child's turn runs, the terminal is a
+    viewer and takes it at its next refresh after the turn, and the page then shows that the
+    conversation is answered in the terminal. An `rpc`, `print` or `json` window does not take it.
+
+    The cost: a stolen token reaches every existing conversation for as long as pi-loops runs, not
+    one session for as long as one terminal stays open, and there is no unauthenticated page any
+    more (`--no-auth` is gone). Rotate it by deleting `web-token` and running `pi-loops restart`;
+    every browser then signs in again. A device that pairs is trusted until the token is rotated.
+    The token is a shell. `/rpc` passes pi's `bash` command, and a prompt reaches pi's `bash` tool,
+    so whoever holds the token runs commands as you, in the project of every conversation.
+    `pi-loops status --url` prints the address with the token in it, so that output is a
+    credential: keep it out of issues, chats and shared terminal logs.
+    A script that runs on this origin (an XSS in the page) still reads the token from memory and the
+    device secret from `localStorage`. A process that holds a sniffed device cookie can load a
+    conversation's page, which starts that conversation's pi as a person's visit does, read the
+    masked stderr tail a crash-looping conversation's page shows and start it again, and spend the
+    twenty tries, which signs that browser out. After `[page] port` changes, a browser pairs
+    again: its secret stays with the old origin. A conversation no lease names opens from one of
+    pi's own session files under its sessions root whose header id is the one in the address
+    (`ConversationIndex.byId`, `src/conversation-rows.ts`), which is what `pi --session <id>`
+    accepts, and which widens what `/c/<id>/` opens from the conversations pi-loops has seen to
+    every one pi has written. `+ New` in a project other than the open conversation's posts
+    `/conversations/new`, which starts a pi in that project with that project's arguments, never
+    the request's; the cost is that a page request can start a pi in any project the page already
+    lists. A project with no arguments of its own gets only `-e <this package>`, and only when a
+    page pi or this process was started with it, so a launch that loads pi-loops with `-e` has
+    pi-loops in every project's conversations without carrying a model or another extension
+    across projects.
+
+22. **A scheduled prompt runs under its own cap, whichever process runs it.** Every request row
+    carries the `mode` its source gets: `attended` for what you typed, a `/goal` continuation, a
+    claim, a recipe hand-off and `/new-trigger`; `unattended` for the clock and an `inject_and_run`
+    push; `none` for a result. The process that runs a row recomputes it and refuses, audited, one
+    that says otherwise, and a window believes an attended source only on a row it wrote itself,
+    so a line in the file cannot widen a turn. An unattended turn runs under
+    the job's declared tools and the dangerous-command policy in a window exactly as in the
+    background; what differs is who answers. The background refuses; a window asks you, with a
+    60-second countdown, and refuses when nobody does, telling the model which of the two it was.
+    pi-loops' own tools get no question from the guard, because each carries its own: `cron_create`
+    makes a job capped to the turn's tools (the window's `toolHost` reads the current turn, as the
+    background scopes a run's), and the tools that confirm through `confirmTool` do so once, where
+    the background's preflight refuses. The cost is a dialog in the middle of a turn
+    you did not start, and `[engine] window_guard = false` buys the uncapped window back. The
+    background process runs no attended row at all; one waits for a window, and a `/cron run` row
+    left in a closed conversation does not hold the clock's slots, which run as if it were not there.
+    `/cron run` is typed: its row goes before the clock's rows.
+
+23. **A chat message from the browser is a request too.** The page posts `/prompt` as before; for
+    chat text `src/web.mjs` appends a `person` row (`kind: input`, `wake: turn`, `mode: attended`,
+    the text and images as the payload, the page's UUID as the id, `created_by` the web.mjs that
+    wrote it) to `requests/<session>.jsonl` and answers `{queued: <id>}` at once. Text that starts
+    with `/`, a steer and Stop stay rpc: they act on the process or on the running turn, not on the
+    queue. The pi holding the session drains the row when it is idle, so a chat message runs in one
+    order with what pi-loops addressed to the conversation, survives Esc and pi exiting, and the
+    page lists the whole queue, each row with its source and a cancel (a `cancel` row), with what pi
+    itself still holds (a command typed while busy) after them, labelled "pi". Two things follow
+    from a row with no `[Trigger]` prefix. Its proof of delivery is a user message whose text starts
+    with the row's (pi appends a note when it resizes or converts an image; a row with no text of its
+    own is proved only by a message with none once those notes are stripped) written at or after
+    `handed_at`, the stamp the drain writes on the row under the lock just before each hand-over, at
+    the moment of the stamp; a turn pi holds and has not written keeps the lane, so one row is in
+    flight at a time, an earlier message with the same words proves nothing, and a row never handed
+    over is never done. Read from the file at every drain and never from an event. In the window, a
+    user message takes the cap of the handed-over row with the longest text that is a prefix of it
+    (a tie goes to the most recently handed over), so a short row's kept cap is not claimed by a
+    longer message. And its attended mode has to be believed: after the append the page sends
+    `/pi-loops ring <id> <fingerprint>` over its pi's rpc stdin, a channel no model tool can write
+    to; the extension records the row as produced by this window only when the row now in the file
+    has that fingerprint (a hash of kind, source, wake, text, the images and the declared tools),
+    then drains; a ring that arrives after the row was handed over upgrades its cap, started or not.
+    A person row is handed over only once rung for, or two seconds after it was written, so the bell
+    normally wins the race with the file watcher, and the drain that waits schedules one for when the
+    wait ends; one nobody rang for (a terminal answering a page's row, owner decision O2; a line
+    written into the file by hand) runs capped as unattended, and the window asks before a dangerous
+    command. `/pi-loops ring` with no arguments only drains; it is plumbing, and not in
+    `/pi-loops help`. A person row is sent only while its web.mjs lives: one left behind when pi
+    exited is offered by the next page as "not sent before pi stopped", with send (which rewrites
+    `created_by` to that page under the lock, then rings) and discard (a `cancel` row). A send pi
+    refuses (`prompt()` throws before any run starts: compaction in progress, no model, no
+    credentials) is found by the holder's tick, or by the drain the page's follow-up ring causes (a
+    command handler, outside pi's event cycle), never by the drain `agent_settled` runs, since pi
+    defers a prompt sent while it emits that event: a row handed to an idle pi with no `agent_start`
+    since, ten seconds after pi's last `input` or `message_start` (its pre-run phase after `input`,
+    the other input handlers and the credential check, is what the grace covers), is refused. A
+    person row gets `last_error` and is never handed over again (its cap is kept, so a send pi runs
+    late still runs under it); the page, which reads the file for `/state`, removes it, audits
+    `failed`, and puts the text back in the composer with the error. A pi-loops row, proved by its
+    prefix, counts an attempt and is offered again after the backoff, a dead letter at the third;
+    a slot due while it waits replaces it rather than collapsing onto it. After Stop (rpc
+    `abort`), as after Esc in a terminal, what is queued runs once pi is idle: the owner decided
+    (2026-11-02) that Esc and Stop end the current turn only, as in 0.22.8, and that the queue is
+    visible and cancellable everywhere instead (the page's per-row ✕, the terminal's `/cron queue`,
+    `queued N` on the status line). The post-abort hold this design first had (a minute for
+    pi-loops' rows, the person's next input for theirs, `released_at` and "send queued (n)" to lift
+    it) is gone with it: a timer that sends words a person stopped was the cost it was meant to avoid,
+    and a queue the person can see and cancel is the plainer answer. Send on an offered row makes the
+    row this page's under the lock, then rings. `handed_at` is not part of the fingerprint. An offered row is listed
+    with its whole text, since send vouches for all of it. The row's image bytes are a file beside
+    the queue, one per row (`requests/<session>.<digest of the id>.images.json`), removed with the
+    row; the row carries each image's type and SHA-256, the fingerprint covers those, and the holder
+    refuses bytes that do not match them, so three screenshots are a line in the queue and not
+    thirty megabytes rewritten under the lock at every update; an append that fails takes the file
+    back, and the background process sweeps files no row names once they are a minute old. Each
+    session's queue has its own lock (`requests/<session>.lock`): one `requests.lock` left by a
+    process killed mid-rewrite held every writer of every session for the stale wait, and now holds
+    that session's alone. A holder that will not deliver a person row says so on its lease: a window standing
+    aside writes `aside` on its holder (`print` and `json` mode are there already; `holderDelivers`
+    in src/lease.ts reads all three), the page's own pi then runs the page's rows it was rung for in
+    that holder's place, and the page does not say "answered there"; when the page's own pi is the
+    one standing aside, the page says so with `/resume` and nothing writes into the conversation. A
+    row of the page's nobody took in fifteen seconds with pi idle (past the ten-second refusal grace,
+    so a refused send comes back as "not sent" and never as both; short of the thirty-second lease
+    tick) is listed as "not taken (why)" with "send it here instead", which removes the row
+    (audited `cancelled`) and sends the text over rpc `prompt`, as 0.22 did; a holder that delivers
+    and is another process is not called unanswering, since the page sees only its own pi's idle
+    state: the row reads "another pi holds this conversation and has not taken it yet (it may be busy)" and
+    the offer "answer here instead (a branch the other pi will not see)". The removal and the check that no
+    holder has stamped the row are one critical section under the queue's lock, and a drain whose
+    stamp finds no row hands nothing over, so a message is answered once. A pi with no pi-loops in
+    it gets chat text over rpc `prompt` and no row is written: nobody would drain it, and the ring
+    would reach the model as the person's message; the command list is asked for again after every
+    slash command (`/reload` changes it) and when it is older than thirty seconds. The
+    cost is a second writer of the request file and a bell on every send; what it buys is a queue
+    that Esc cannot clear and a message that outlives the process it was typed into.
+
+    A claim from the page's inbox (**Yes, do it**, **Look into it**) is not a `person` row: it is
+    the `inbox:<id>` row `/inbox claim` writes, with the same collapse key, so a page and a terminal
+    claiming one finding collapse on each other and the file lock settles which one wrote it. The
+    page server signs it and lives on, and a row its producer outlives would wait for it for ever,
+    so the row is born left (`created_by.left` set at birth, `pageClaimRow` in src/engine.ts): the
+    holder runs it, as it runs a terminal's claim after that window moved on, and nobody else does,
+    since a viewer runs only its own rows and a left row is nobody's, and pi-loops in the background
+    runs no attended row. Under the inbox's lock, once `Inbox.decide` has found the finding still
+    new, the server writes the row and then marks the finding claimed, so a claim that loses writes
+    nothing (a terminal's `/inbox claim` does the same in `handOver`); then it delivers: it
+    rings the page's pi that holds the conversation, leaves the row to a terminal that holds it, waits
+    out pi-loops' scheduled turn there, or starts the conversation's pi when nobody holds it, asking
+    for its command list first and never ringing, or starting again, a pi with no pi-loops in it. The
+    same step runs at start and every ten seconds, one at a time (a claim made while one runs says
+    where it will run and is delivered when that one ends), so a claim tapped on a phone and left there runs
+    when the conversation is free, and a claim cut short between the row and the status is finished
+    from the files. The cost is the one this decision already pays for a page's message: in a
+    terminal the claim's turn runs capped as unattended, since no ring reaches a terminal, and the
+    danger check asks in that terminal before a dangerous command.
+
+24. **A watch is a question the tool asks.** With a person present, in the person's own turn
+    (hop 0, `ctx.hasUI`, not a scheduled turn), `cron_create` and `new_trigger` run every check a
+    create would, then ask through pi's own `ctx.ui.select` and wait for the answer in the same
+    call. The title is `Set up this watch?` and then the card's rows as `Label: value` lines
+    (`Runs` or `Waits for`, `Looks`, `Does` or `Then`, `Careful`, `Command`; a value's
+    further lines are indented two spaces). The options are a fixed vocabulary, one string per
+    combination of the card's choices, the plan's defaults first: for a schedule
+    `Set it up · inbox`, `Set it up · inbox · with checks`, `Set it up · this conversation`; for a
+    rule `Set it up · this conversation|inbox · once|every time`; and `Cancel`.
+    `watchChoice` in `src/watch-plan.ts` is the one place an answer becomes the stores' fields: a
+    schedule's `inbox` is `stateful` and `with checks` is `verify`; a rule's
+    `this conversation` is `promote_to_chat` and `once` is `fire_once`. An answer that was not
+    offered is a cancel. The tool returns `created cron job …` or `created dynamic trigger …`, or
+    `cancelled: the person did not set up this watch (Cancel|aborted|timed out). Nothing was
+    created.`, and the model reads that one rule on every surface. The question replaces
+    `new_trigger`'s confirm: one question, never two. A terminal shows pi's selector; the page draws
+    the same select as its card (chips are the axes of the options, Set it up sends the option they
+    name through `/ui-response`), and the tool result in the same turn turns the card into a
+    receipt. The page's child drops every dialog asked since the last `agent_start` when the run
+    ends, since pi has answered it by then and tells nobody: replayed, it would be a card whose
+    answer goes nowhere. A sub-agent, pi-loops in the background, a pi with no dialog and a
+    scheduled turn in an open window ask nobody and keep their gate: `cron_create` creates at once
+    and `new_trigger` asks the window guard's confirm or is refused. The sentence itself is an
+    ordinary chat message, `Watch for: <sentence>`; a sentence with no time and nothing to wait
+    for is answered by the page and reaches no model, and both tool descriptions say at hop 0 that
+    such a message is never acted on now. The question shows no directory, so a `cwd` outside the
+    project is refused before it is asked.
+    What it costs: the turn waits on the person, up to thirty minutes, and then the question is
+    cancelled and nothing is created; tool calls in a turn are sequential, so the turn's other work
+    waits too, and a plain job that comes due in that window queues behind it. The card lives in
+    the dialog, not in the transcript: a conversation read later shows the tool result and no card,
+    and a question still open when its pi stops is gone with it. A second identical call in one
+    turn is a second question; the result tells the model not to call again, and nothing enforces it.
+
+
+25. **A run writes into the conversation only when there is something to see.** A loop's first three
+    runs and every failed run are one compact card each, saved in the conversation that created the
+    loop; every other run is a line in the terminal's panel and the page's activity strip, read from
+    `runs.jsonl` when asked, with no store of its own. Deciding needs to know which run of its loop a
+    run was, and the run log is halved as it grows, so the record carries it (`ordinal`), and a
+    stopped run carries `aborted`, which is neither a failure nor a card. A 15-minute loop writes
+    three entries into its conversation, not 96 a day. The cost: a loop that has worked for a week
+    and then fails at night shows that failure, and nothing of the runs before it, in the
+    conversation; the strip and `/cron runs` have those.
+
+    Every matched rule result is one finding in the inbox, whatever `promote_to_chat` says; with
+    `promote_to_chat` it is also in the conversation. `Inbox.appendOnce` is the one rule that keeps
+    it one finding when the promotion falls back to the inbox or its row dies, the three writers that
+    used to file it. A rule result is filed as news: its text comes from outside, and a `· waits:`
+    in it would otherwise make a "Needs you" card and a notification on every page. A repeating
+    rule that says what its latest new finding says files nothing, or it would fill the inbox one
+    poll at a time. The cost: a result read in the chat waits in the inbox too, until someone
+    dismisses it.
+
+    A terminal writes `turnSince` on its lease while a turn runs, as the page's pi does, and `turns`
+    says it will. The page reads a terminal-held conversation from the file with pi's exported
+    parse, migration and projection functions instead of switching its own pi to it, and reads it
+    again once the turn is over and a new message is there. The read is synchronous in the process
+    every page shares, so a file over 32 MB is left to the page's pi. A switch changed the epoch under the
+    page and answered `get_messages` from either session; a guess at the end of a turn from 8 s of
+    quiet read half a turn. The cost: two small lease writes per terminal turn, and a terminal
+    older than 0.24 is never read again by the page.
+
+26. **A condition that is only a path is looked at with `stat` first.** A rule such as "when
+    ~/build.done appears" used to cost a model call every poll, for hours, to learn that one file was
+    not there yet. `src/path-precheck.ts` decides when the rule is created whether its condition is
+    only "a path exists or appears", resolves `~` and `$HOME` in the creating process, and records
+    the result on the rule (`precheck`). Each poll, after the poll ledger's claim, `stat`s the path
+    (2 s timeout, one in flight per rule); while it is absent the rule stays out of the check's
+    prompt and no `running` row is written, and the audit says `waiting` once. Anything the stat
+    cannot answer goes to the model, so a refusal or a doubt costs what it cost before and never a
+    match. The costs: a condition worded outside the grammar still bills; the grammar knows English
+    and Chinese only; a rule created before 0.24.0 keeps billing until it is created again, because
+    the path was never resolved by the person's own process; and a repeating rule still matches
+    every poll while the file stays, as it always did.
+
+27. **What happened while you were away is counted per project.** One cursor per project in
+    `seen.json`, moved by `/inbox` in any of its conversations and by the page's **Mark all seen**;
+    the terminal's session-start line and the page's away card are one function over the same files
+    (`src/seen.ts` `awayFor`). Every loop of the project counts, a recipe's included, and a finding
+    from this conversation is marked as such. The cost: a look in one conversation clears the
+    count for all of them, and the page's mark clears the terminal's next line. A cursor per
+    conversation was the alternative, and it is what left a recipe's findings out: they belonged
+    to the one conversation that installed it. With no cursor the first count is the last day,
+    never the whole run log.
 
 ## Where the browser front end came from
 
@@ -208,7 +538,7 @@ goes through the door pi already provides: `pi --mode rpc` — pi with no termin
 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
+what they exposed, the active tools, whether pi-loops is running and its pid — 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
@@ -224,13 +554,22 @@ pretending. What the page owes you is kept as a gate rather than a wish list in
 
 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
+without anything of yours passing through a third party, and `[page] 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)).
+While nobody is at the terminal, pi-loops’ control channel is what answers "what is it doing":
+`pi-loops status|abort|stop` ([cli.md](cli.md)), and the Background view of the page, which
+`tailscale serve` puts on a phone the same way.
+
+In 0.24 the page moved out of the terminal. Until then `pi-loops` ran the page's server and its one
+pi itself, so closing that terminal took the page off the phone, and pi-loops in the background
+served a separate read-only status page on 4174. Now pi-loops in the background serves the one page
+on 4173, with a pi for each open conversation, and `pi-loops` only asks it to open one and exits
+(decision 21). `src/web.mjs` keeps the page strings; the server is `src/page-server.ts`. The
+listener flags became `[page]` in `config.toml`, because a page that outlives the command cannot
+take its address from one.
 
 ## What this is not
 

package/docs/downstream.md

@@ -4,7 +4,7 @@ Three things, and this page is the whole list. A program that is not pi-loops an
 its source may rely on these and on nothing else.
 
 **Any file under `~/.pi/agent/loops/` is not an interface.** `jobs.json`, `inbox.jsonl`,
-`runs.jsonl`, `state/`, `host.json`, the logs: private, and they change without notice. The one
+`runs.jsonl`, `state/`, `host-service.json`, the logs: private, and they change without notice. The one
 file there a program writes is `hooks.toml`, and only for the two events below. The same goes for
 every command, field and path this page does not name, the wording of the slash commands, and the
 browser page.
@@ -23,7 +23,7 @@ breaks a rule is refused before anything is copied.
 ## 2. `run_start` and `run_end` in `hooks.toml`
 
 A `[[hook]]` rule with `event = "run_start"` or `event = "run_end"` fires around every scheduled
-run, in a pi window and in the headless host alike; what the payload carries is
+run, in the background, where every loop runs; what the payload carries is
 [CONTRACT.md](../CONTRACT.md) §2.2, and the file, the rule keys and when the two fire are in
 [hooks.md](hooks.md#exactly-when-hooks-fire). Each field reaches the rule's command as a `PI_*`
 variable, unset where the payload has `null`, and all of them together as JSON in the file at

package/docs/goal.md

@@ -34,9 +34,14 @@ is told to answer `{"ok": false, "reason": "insufficient evidence in transcript"
 | Interruption | Esc on a turn pauses the goal — it stays paused across `--resume` until `/goal resume` — and Esc during an evaluation stops that evaluation the same way |
 | Its own timeout | 2 minutes; it is one read, not a piece of work |
 
-`/goal resume` after a budget limit starts the allowance again, and after an Esc starts
+`/goal resume` after a budget limit starts the allowance again (also when you paused it in
+between), and after an Esc starts
 evaluating again: stopping a turn is taken as stopping the goal, since the next message you sent
-would otherwise end with the evaluator sending the agent back to work. `pause`, `resume` and `clear` are
+would otherwise end with the evaluator sending the agent back to work. A `/goal` command typed
+while an evaluation runs stops that evaluation, and what it would have decided is discarded: the
+command has already set the goal you asked for. A turn that settles while the evaluator is still reading (you
+asked something meanwhile) is judged as soon as that evaluation returns, so a continuation held for
+it does not wait for you to type 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.
 
@@ -53,7 +58,11 @@ than dropping 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
+up where it left off. A continuation is a request addressed to the session
+(`requests/<session>.jsonl`), handed to the agent once it is idle: a window that quits leaves it for the next one while the goal is
+pursued, and a continuation on its way is not judged again, so it is charged once. Esc pauses the
+goal, and a continuation still queued for it is dropped with it; `/goal resume` judges the next turn
+afresh. The status line shows `goal: <status>`; the
 statuses are `pursuing`, `paused`, `achieved`, `budget_limited` and `cleared` (what `/goal clear`
 leaves behind).