@alphacoder-v0/pi-loops 0.22.7 → 0.24.0

package/docs/hooks.md

@@ -30,7 +30,7 @@ Authorization = "Bearer your-token"
   as `hook <source> <event>: <output>` — redacted and rotated like everything else there, and cut
   off after 4000 characters so a chatty hook cannot rotate away the night's history. `echo` and
   read the file is the usual way to find out what a hook did. stderr is still kept for the failure
-  message only. The headless host does the same into `host.log`, which is where the question is
+  message only. pi-loops does the same into `host.log`, which is where the question is
   usually asked.
 - Webhooks receive `Content-Type: application/json` with a payload whose every field is always
   present, `null` when it does not apply. `message_kind` is `user` | `assistant` | `tool_result`
@@ -76,9 +76,8 @@ Authorization = "Bearer your-token"
   you are talking to fires them. Sub-agent sessions — loop runs, checkers, trigger checks — fire
   nothing: they are not the session you are in.
 - **`run_start` and `run_end` are about a scheduled run**, and they fire wherever the run happens:
-  in the pi you are talking to, and in the headless host ([loops.md](loops.md)). Whether a 3am job
-  ran under a host or under a pi you left open is an accident of who held the clock, and a hook rule
-  should not be able to tell.
+  which is pi-loops: every loop runs in the background ([loops.md](loops.md)). A plain job is a message in a
+  conversation, not a run, and fires neither.
 
   They exist because a scheduled run is not a turn. It happens with no conversation at all, or
   beside one — and overloading `agent_*` would mean a rule you wrote about your own turns quietly
@@ -96,15 +95,15 @@ Authorization = "Bearer your-token"
   command = '[ "$PI_RUN_OK" = false ] && notify-send "loop $PI_RUN_JOB failed" "$PI_RUN_ERROR"'
   ```
 
-  In the host, where there is no conversation, `session_id` is the run id and `cwd` — including any
+  In pi-loops, where there is no conversation, `session_id` is the run id and `cwd` — including any
   `cwd = "project"` rule — is the job's directory.
 
 - `run_*` hooks are always queued off the run, whatever `[hooks] mode` says, in both processes — a
   webhook that hangs must not hold up the clock, and the run it announces has already started or
   already finished. `mode = "sync"` is about ordering within a conversation turn, and a run is not
-  one. The host drains for up to 3 seconds when it exits. Failures go to the host log,
+  one. pi-loops drains for up to 3 seconds when it exits. Failures go to pi-loops log,
   `~/.pi/agent/loops/host.log`.
 
-- Project hooks in the host additionally need the job's cwd to be a directory you trusted in pi
+- Project hooks in the background additionally need the job's cwd to be a directory you trusted in pi
   (that exact directory, not an ancestor): a job's cwd can be chosen by a model, and nobody is
   there to answer a trust prompt.

package/docs/loops.md

@@ -8,16 +8,87 @@ Everything here is `/cron`; `/crontab` and `/loop` are the same command under ot
 /cron add "*/30 * * * *" summarize the repo state
 ```
 
-When due, the prompt is injected into the session that created the job as a user message with the
-engine prefix `[Trigger <run-id>] `, and the agent runs one turn (an *inject-and-run* job). If the agent
-is busy the message is queued as a follow-up. A plain job belongs to the session that created it:
+When due, the prompt is written as a request addressed to the session that created the job
+(`requests/<session>.jsonl`), and the window holding that session hands it to the agent as a user
+message with the engine prefix `[Trigger <run-id>] ` once the agent is idle; the agent runs one turn
+(an *inject-and-run* job). While the agent is busy the prompt waits in the queue, where Esc cannot
+drop it and a window that quits leaves it for the next one, and runs once the agent is idle, as a
+message you queued in a chat does: Esc, and the browser's Stop, end the current turn only. In
+exchange the queue is visible and cancellable: the window says `queued: cron <name> runs after the
+current turn` when the prompt is queued behind a busy turn, the status line shows `queued N` while
+rows wait for this conversation, and `/cron queue` lists them numbered with their source, age and
+text; `/cron queue cancel <n|id>` takes one out and `/cron queue clear` all of them, each cancel
+audited. While the prompt waits, `/cron` marks the job `[queued <how long>]`,
+with the reason when the queue knows one (`backing off until <when>` after a hand-over that failed),
+and `cron_list` reports `queued` with `since`. A hand-over pi does not take (no model, no
+credentials, another extension's input handler swallowing it: pi starts no turn and tells the
+extension nothing) is judged ten seconds after pi's last input event, with pi idle, and offered
+again after a minute, then five; the third refusal makes the prompt a finding in the inbox and frees
+the job, and a slot due while a refused prompt waits replaces it instead of being skipped onto it,
+so one refusal costs one slot, as it did in 0.22. A prompt pi dropped before writing it (Esc, or an
+input handler that rewrote the `[Trigger <id>] ` prefix away) is offered again at most three times,
+each turn under the job's cap, then goes to the inbox the same way. The prompt of a job you disabled
+waits in the queue until you enable it again; a prompt `/cron run` queued runs even if the job was
+disabled since, because you asked for it. A one-shot job is removed once its prompt is in the
+conversation, not when it is queued. A plain job belongs to the session that created it:
 its result is a message in that conversation, so it fires only in the process holding that session.
-Open another session and `/cron` lists it as `[session <id> — resume it to run]` with no next run,
-`cron_list` says the same to the model, and `/cron run` refuses it; `--resume` the session it
-belongs to and it wakes, catching up a missed slot if it was created with `--catchup`. It is not
-broken while it sleeps — it is waiting for its conversation. Something that should run whether or
-not a window is open (a nightly digest, a watch) is a loop: `--stateful`, with the inbox as its
-outlet.
+One window holds a conversation at a time. Open the same conversation in a second window and that
+window is a viewer: it fires none of the conversation's plain jobs, `/cron` there marks each one
+`[session <id> — open in a terminal]` (or `in the page`) with its next run, and `/cron run` says
+where to run it.
+When the holding window closes, the viewer takes the conversation over on its next tick. If the
+other window added turns after the viewer opened the conversation, the viewer's copy is older than
+the file, and a turn fired there would leave those turns on a dead branch. So that window says to
+`/resume` the conversation, and its plain jobs and rule results wait until you do: `/cron` there
+marks each one `[session <id> — this window shows an older copy; /resume it to run here]`, and
+`/cron run` says the same.
+When no window holds the conversation, pi-loops fires the job in it: it takes the conversation for
+that one turn, runs the prompt there on the conversation's own model (a plain job pins none, and a
+`model` a 0.22 chat stored on one is ignored) as the conversation's own turn, so `cron_create`,
+`cron_list all_projects` and the other tools act for that conversation and a control-plane confirm
+is refused with a sentence that says the turn ran in the background with nobody to ask,
+and gives it back, so the answer is in the conversation when you resume it. `/cron` in another
+window marks such a job `[session <id> — in the background]`, with its next run. pi-loops leaves a
+conversation alone while someone else has written its file in the last two minutes (its own last
+write does not count). A window that opens the conversation during pi-loops' turn takes it back at
+once: the turn stops at its next step, the slot is owed, and that window runs the job straight away,
+even long after its due time and with catch-up off, because the slot was tried, not missed. A turn
+pi-loops stops itself (`pi-loops stop`, an upgrade, the daily budget) is owed the same way and runs
+on pi-loops' next tick. A turn you stop (`/triggers abort`, `pi-loops abort`) is done: the slot is
+spent and the prompt does not run again. Each turn is a run: it appears in `/cron runs` with its
+cost, a failure sets the job's error and the same backoff a loop gets, and a one-shot that fails is
+tried once more before it is retired. A conversation pi-loops has never seen open in a window (its
+file is unknown) is asleep: `[session <id> — resume it to run]` with no next run, and `/cron run`
+refuses it. When pi-loops is not running, the job shows `paused: <why>` instead. The daily budget (`[limits] daily_budget_usd`) covers these
+turns as it covers loop runs, counting only what each turn adds, not the conversation's history. The
+pi-loops loads a conversation's extensions once for its turns and releases them after an hour without
+one. Something whose result should not land in a conversation (a nightly
+digest, a watch) is a loop: `--stateful`, with the inbox as its outlet.
+
+A plain job's turn is a scheduled turn wherever it runs, and it runs under the job's own `--tools`
+and the dangerous-command policy (below) in an open window as in the background. So does the turn an
+MCP server's `inject_and_run` push starts ([mcp.md](mcp.md)), with no declared tools: the
+dangerous-command policy alone. The difference is
+who answers. In the background a call outside them is refused. In a window, while the job's turn
+runs, such a call asks you first: a question with a 60-second countdown and two answers, `No, refuse
+it` focused and `Yes, run it once` under it, so Enter refuses. The yes answer runs it this once;
+anything else, Escape or no answer refuses it and tells the model why, so it does the safe part and reports:
+your No is reported as your refusal, no answer as nobody being there. A
+message you send into that turn makes the rest of it yours and nothing asks again. Your own turns, a
+`/goal` continuation, a claimed finding, a recipe hand-off, `/new-trigger` and `/cron run` never ask.
+pi-loops' own tools are not asked about a second time: `cron_create` in such a turn makes a job
+capped to the turn's tools, as a job a background run makes is capped to that run's, and
+`new_trigger`, the trigger tools, `cron_remove` and `set_cron_job_state` ask through their own
+confirm, once, where the background would refuse.
+With you present, in your own turn, `cron_create` asks you before it creates anything: pi's selector
+in a terminal, the same question drawn as a card in the browser page. The first answer is the
+model's own choice: *Put it in my inbox* (a loop, with its notes between runs, with or without a
+checker) or *Show it in this conversation* (a plain job of this conversation). The tool returns
+`created cron job …` or `cancelled: …` in the same call; Cancel, Esc and thirty minutes with no
+answer write nothing. The question shows no directory, so a `cwd` outside this project is refused
+before it is asked ([design.md](design.md), decision 24).
+`[engine] window_guard = false` in `config.toml` turns the cap off in windows
+([configuration.md](configuration.md)).
 
 Schedules are local time: 5-field cron (`*/n`, ranges, lists, `mon-fri`, `jan`), the aliases
 (`hourly` / `every hour` / `once an hour` → `0 * * * *`; `daily` / `every day` → `0 9 * * *`;
@@ -31,8 +102,11 @@ Schedules are local time: 5-field cron (`*/n`, ranges, lists, `mon-fri`, `jan`),
 /cron add --stateful "0 9 * * *" check the repo issues and report anything new since the last run
 ```
 
-Each run is a fresh sub-session inside the interactive pi, through pi's SDK: full tools including the parent's live MCP servers, the session's model and thinking
-level, no conversation history, its own transcript file. Every run gets the same prompt: the output
+Each run is a fresh sub-session in pi-loops in the background, through pi's SDK: the built-in
+tools of the chat the loop was made in (or its `--tools`), the MCP servers it connects itself from
+`mcp.toml` and the project, the model and thinking level of the chat it was made in, no
+conversation history, its own transcript file. It does not get the window's `-e` extensions, flags
+or live MCP connections. Every run gets the same prompt: the output
 protocol, preceded by one line of context (the job's name, when the run started, whether it is a
 catch-up):
 
@@ -59,9 +133,40 @@ Then:
 - missing or malformed tags never fail a run: the state stays untouched, nothing enters the inbox;
 - a run that is still going when the next tick arrives is skipped and counted (`skipped overlaps`).
 
-Every run leaves a trail: the sub-agent's full transcript (`/cron trace <job> [k]`, 20 per job), a
-run log with exit code, duration, cost and finding counts (`/cron runs`), and a card in the
-transcript when the run finishes. Prompts are capped at 8 KB.
+Every run leaves a trail: the sub-agent's full transcript (`/cron trace <job> [k]`, 20 per job) and
+a run log with exit code, duration, cost and finding counts (`/cron runs`). Prompts are capped at 8 KB.
+
+### Run cards
+
+A run writes into the conversation that created its loop only when there is something to see:
+
+- a loop's first three runs each get one compact card, so you see that it works and what it reports;
+- every failed run gets a card, and a terminal also shows it as a warning;
+- a run a person asked for (`/cron run <loop>`, or the run button in the page) gets a card in the
+  conversation that asked, whatever its place among the loop's runs and whichever conversation created
+  the loop. Its card also shows the first line of the run's reply, cut at 120 characters, with escape
+  codes and bidi controls taken out;
+- a terminal and the page's pi save a card the same way: the page draws it when it is saved and when
+  it reads the conversation again. A window that does not hold the conversation only shows the line.
+  The page does not draw the cards of a conversation whose session file is over 32 MB: reading its
+  entries would hold up every page. A conversation a terminal holds also shows, in the page, the
+  pi-loops views that terminal wrote into it (`/cron`, `/inbox`), redacted and cut at 4000 characters;
+- every other run writes nothing into the conversation. A terminal lists the latest three loop runs of
+  the project in the panel above the editor (`Runs`), the page lists the project's runs and rule results
+  of the last day in its loop activity strip above the composer, and `/cron runs` has them all.
+
+A card is one line: `todo · 5s · $0.003 · 1 finding`, or `todo FAILED · 4s · <error>`; a loop with no name is labelled by the first 13 characters of its id (`cron-15c11c9f`), as every surface but `/cron`, `cron_list` and `inbox --json` labels it. It
+is saved in the conversation, so a resumed conversation still shows how its loop started, and
+`/session-share` leaves it out. A run that was stopped (by a person, a quit or a restart) is not a
+failure and gets no card. When more than five carded runs finish between two looks at the run log,
+five are shown and the rest is one line: `+4 more runs finished (4 failed) — /cron runs`.
+
+Who asked for a run is in its run log record as `requestedBy: { sessionId }`. A scheduled run, and a
+record written before 0.24.0, has none.
+
+A run's place among its loop's runs is in its run log record (`ordinal`). A stopped run does not
+count, so the run after it has the same place. A record written before 0.24 has no place and is not
+one of the first three.
 
 ## The inbox
 
@@ -70,10 +175,14 @@ Global JSONL, shared by every session and project. Each line is one finding in t
 `cron-<32 hex>`; prefixes, names and list numbers resolve.
 
 ```text
-/inbox                 Inbox (<project>, N new, K need a decision, times <offset>): "<n>. [<id prefix>] <finding>  (<project>, <source>, <created_at>)"
+/inbox                 Inbox (<project>, N new, K need a decision, times <offset>): "<n>. [<id prefix>] <finding>  (<project>, <loop label or source>, <created_at>)"
+                       a decision is listed on up to three lines, its clauses under it:
+                       "<n>. [<id prefix>] ⚑ <decision>  (<project>, <source>, <created_at>)"
+                       "       waiting on: <what waits on it>"
+                       "       if you don't: <what happens if nobody acts>"   (left out when the loop left it out)
 /inbox --all           the same, every project on this machine
 /inbox all [--all]     history including claimed and dismissed
-/inbox claim <n|id>    mark claimed and start a real agent turn:
+/inbox claim <n|id>    mark claimed and queue a real agent turn, run once the agent is idle:
                        "A recurring loop (<source>, running in <cwd>) reported this finding — investigate and address it: …"
                        (the loop's cwd is part of the line; a checker-kept finding adds a line saying so)
 /inbox dismiss <n|id> [reason]   mark dismissed; the reason, if you give one, is shown to the loop's next run
@@ -100,6 +209,43 @@ while an id or an id prefix still resolves machine-wide. `/inbox clear` dismisse
 not the unread findings of four other projects. A finding stored without a cwd belongs to no
 project and is listed in all of them.
 
+A loop's finding names the conversation that created the loop and the transcript of the run that
+filed it. What happened while nobody looked is counted per project: when a conversation starts,
+one line counts the project's loop runs and new findings since `/inbox` was last listed in any
+conversation of the project, or the page's **Mark all seen** was pressed for it:
+`[inbox] since you last looked (yesterday 23:10): 41 loop runs (3 failed), 3 new findings (1 from
+this conversation) — /inbox`. Every loop of the project counts, a recipe's included, whichever
+conversation created it; `from this conversation` counts the findings whose loop or rule was made
+in this one, and is said only when that is not every finding. A loop that belongs to its project rather than a conversation (a recipe installed in
+a conversation pi had not saved yet, [recipes.md](recipes.md)) is counted in the project and is
+from no conversation; its finding runs in the conversation you claim it from (**Yes, do it here**), and
+`pi-loops inbox claim` marks it claimed with no conversation to act on it, so the caller handles it
+([cli.md](cli.md#inbox)). Such a loop is stored with `owner:
+"project"` and no `createdBy`, and a `.pisession` archive keeps it the project's on import. A
+rule check that filed a finding for two conversations is one finding. A stopped run
+is a run, not a failure. A finding counts while it is new, and a finding stored without a cwd
+counts in every project, as `/inbox` lists it. The time is local: `09:14` today, `yesterday
+23:10`, a weekday within the week, a date before that.
+
+Listing `/inbox` clears the line for the project, in every conversation of it and in the page;
+`/inbox --all` clears it for every project. The page's away card counts the same way, from the
+same function (it says the findings and leaves the runs to the activity strip), and its **Mark all seen** clears the terminal's line too: the next session start
+says nothing until something new happens. Marking moves only the cursor; the findings stay new.
+The terminal's `/inbox` marks the time it finished listing, so a finding filed in the milliseconds
+while it listed counts as seen; the page sends the time of the answer its card shows, so what
+arrived after that is still counted.
+The cursors are in `seen.json`, one per project. When nobody has looked yet (a new project, or the
+first start after an upgrade from 0.22.x, which kept no cursor), the line counts the last day
+(`(in the last day)`), never the whole run log. A cursor from an older 0.24 build, kept per
+conversation, counts for the project its conversation's records are in, so nothing is counted
+twice. A cursor more than five minutes ahead of the clock counts as none, and the next look
+replaces it. A clock moved back can hide records written in the gap until the next look.
+
+`/inbox open <n|id>` starts a new conversation from the run that filed the finding: pi copies the
+run's transcript into a new session and switches to it, and the run's own transcript is never
+written. A transcript a new finding points at is kept when older runs are pruned, up to 100 per
+loop; one that is gone anyway is reported as such.
+
 A finding that asks for a decision is a **checkpoint**, and the inbox knows one by its shape:
 the ` · waits: … · if not: …` clauses every packaged playbook writes
 ([recipes.md](recipes.md#checkpoints)). The run's text is read once, when its findings are
@@ -108,12 +254,34 @@ lists checkpoints first, marked `⚑`, and says how many there are in its header
 decision`); the numbers on screen are the numbers `claim` and `dismiss` take, so the order is
 decided in one place. Claiming a checkpoint tells the turn that the claim is the person's approval
 of the decision the finding recommends, and to carry it out rather than investigate it again.
-
-Corrupt lines are skipped on read and never deleted. The footer shows `Inbox: N new`, with
-`(K decisions)` after it when any are checkpoints (the whole machine, as the badge always has), and `N job(s) failing (<worst> ×<count>)` once a loop has failed
+`/inbox`, `pi-loops inbox list` and the page read a finding through one parser
+(`src/inbox-card.ts`): a checkpoint's headline is the text before `· waits:`, and its two clauses
+are shown apart as **waiting on** and **if you don't**; a clause the loop left out is not shown.
+The stored line does not change. `pi-loops inbox list --json` prints the stored fields, unsplit.
+
+The browser page shows this project's findings as cards above its conversations, decisions first.
+**Yes, do it** (on news, **Look into it**) queues the claim in the conversation that created the
+loop, as the same `inbox:<id>` row `/inbox claim` writes: a terminal that holds that conversation
+answers it under the danger check, a conversation open in the page runs it as your turn, and one
+nobody holds is started. When that conversation is gone, the claim goes to the conversation open
+on the page, if it is in the finding's project. **No…** (on news, **Dismiss…**) takes a reason
+chip or a typed reason of up to 500 characters, which goes to the loop's next run as the terminal's
+reason does; with none it is a silent dismiss. **See the run**, on a finding that names its run,
+shows the run's transcript, read-only. A card names its loop only when the list holds more than one
+loop's findings, and says where a claim runs only when that is not the conversation on screen.
+
+Claim and dismiss each succeed once, and only on a finding that is still new: two windows, a
+window and a shell, or two pages that both listed it get one success between them, and the other
+is told the finding was already claimed or dismissed. A claim queues its hand-off under the inbox's
+lock, only once it has found the finding still new, so a claim that loses queues nothing and the
+finding's turn runs once, also while another process holds the lock.
+
+Corrupt lines are skipped on read and never deleted: a claim, a dismiss, `/inbox clear` and
+rotation write them back as they were, in their place. The footer shows `Inbox: N new`, with
+`(K decisions)` after it when any are checkpoints (the whole machine, as the badge always has), and `N loops failing (<worst> ×<count>)` once a loop has failed
 often enough for the scheduler to start backing off; the same clause is on the `[cron] … active
 here` line at session start, for this project. Until then a job that has failed forty nights in a
-row looked exactly like a healthy one. The side panel shows the inbox count too. Entries kept by
+row looked exactly like a healthy one. Entries kept by
 the checker carry a `✓`.
 
 ## Maker/checker (`--verify`)
@@ -126,27 +294,31 @@ and answer with one `<verdict n="i">keep|drop — reason</verdict>` per finding
 `<rewrite n="i">…</rewrite>`).
 
 - Kept findings enter the inbox marked verified; the checker's reason travels with the claim.
-- Dropped findings and their reasons go to the run log and the run card; `/cron trace <job> <k> checker` shows the checker's transcript.
+- Dropped findings and their reasons go to the run log; `/cron trace <job> <k> checker` shows the checker's transcript.
 - Findings without a verdict enter unverified.
 - **Fail-open:** if the checker fails or times out, every finding enters the inbox marked unverified. A broken checker must not silence the loop.
 - The checker never touches the state spine.
 
 ## Restart behavior
 
-Jobs live in `~/.pi/agent/loops/jobs.json` and survive pi restarts. Exactly one pi process on the
-machine owns the timer (`scheduler.json`, 30-second ticks, 90-second heartbeat); when it exits
-or dies another open pi takes over on its next tick. A tick that was missed while no pi was running
-is fired once at startup (collapsed, not replayed) for stateful loops unless `[cron] catch_up = false`;
-plain inject jobs do not catch up unless created with `--catchup` (`--no-catchup` turns it off for
-loops). A run that died with its process is retried on the next tick; at most
+Jobs live in `~/.pi/agent/loops/jobs.json` and survive pi restarts. Stateful loops run in one
+always-on process ([pi-loops in the background](#pi-loops-in-the-background)), which ticks every 30 seconds. A loop tick that was
+missed while pi-loops was not running is fired once when it starts (collapsed, not replayed) unless
+`[cron] catch_up = false`; a loop that does not catch up records `missed <time> while pi-loops was
+not running (catch-up disabled)`. Plain inject jobs do not catch up unless created with `--catchup`
+(`--no-catchup` turns it off for loops), and a missed one records `missed <time> while no pi was
+running (catch-up disabled)` in a window, or `while pi-loops was not running` in the background. A run that died with its process is retried on the next tick; at most
 `[cron] max_concurrent_runs` (3) run at once. Trigger checks share `[cron] max_concurrent_runs`, so
 a server pushing many distinct events cannot open one sub-agent per event.
 Jobs run with the model and thinking level recorded
-on them (`/cron set <id> --model … --thinking … --timeout …`, `-` to follow the running session).
-`/cron scheduler` shows who owns the timer; `/cron` marks a plain job as `[session <id> — resume it
-to run]` when its session is not open here, parks it as disabled once that session's file has been
-deleted (`/cron gc` removes it), and marks a loop `[orphan: cwd missing]` when their checkout is gone — disabled half an hour later, since a
-mount can be late at boot. A job created by a sub-agent belongs to the session that ran it.
+on them (`/cron set <id> --model … --thinking … --timeout …`; `-` clears one: a loop then uses pi's
+default, a plain job its conversation's).
+`/cron scheduler` shows this window (its pid, and whether its conversation's plain jobs run here),
+pi-loops (pid, version, start time), the store and the log. `/cron` marks another conversation's plain
+job `open in a terminal`, `in the page`, `in the background`, `paused: <why>`, or `resume it to run` (pi-loops never saw its file), parks it as disabled once that session's file has been
+deleted (`/cron gc` removes it), and marks a loop `[orphan: cwd missing]` when its checkout is gone
+— disabled half an hour later, since a mount can be late at boot. A job created by a sub-agent
+belongs to the session that ran it.
 
 pi-loops runs on one machine. Two machines syncing one `$HOME` would both run every job; that is
 not supported (until 0.19.0 a hostname stamp on each job half-handled it, and is now ignored). To
@@ -248,7 +420,10 @@ audit like any other.
 an `every <dur>` job's interval restarts from now, and a `cron` job's next run is unchanged — the
 expression says when it runs, not the last run. A disabled plain job is refused rather than run: its
 prompt would land in whichever chat is open now rather than the one it was written for, and a job the
-dead-session sweep parked has to keep the marker `/cron gc` collects it by.
+dead-session sweep parked has to keep the marker `/cron gc` collects it by. A plain job's `/cron run`
+is your own turn: it runs uncapped and goes before anything the clock queued. Left queued when you
+quit, it waits for a window, and the job's
+schedule goes on in the background as if it were not there.
 
 A project is matched by realpath and containment, so a pi opened in a subdirectory, a worktree or
 through a symlink sees and runs that project's automation.
@@ -295,8 +470,9 @@ not finish, so its `<loop-state>` and `<inbox>` tags are not trusted.
 ## Stopping, removing, and jobs that keep failing
 
 `/cron disable --all` pauses every job in this project (`--all-projects` for the machine) and
-`/cron enable --all` resumes them — quitting pi hands the clock to the host rather than stopping
-anything, so this is how you actually go quiet.
+`/cron enable --all` resumes them. Closing every pi window stops nothing, because pi-loops keeps
+running, so this is how you actually go quiet; `/pi-loops stop` pauses every loop and check on the
+machine until `/pi-loops start`.
 
 If a loop is stuck showing `running` after a process was killed and its pid reused, `/cron clear
 <ref>` releases the marker (it asks first).
@@ -310,6 +486,14 @@ this project is named with the project it was in.
 `/cron set` instead); `--purge` deletes them. `/cron gc` collects this project's jobs whose session
 is gone — `--all` every project's, `--purge` also the loop state and transcripts left behind by jobs that are gone.
 
+A loop run you stop (`pi-loops abort <run-id>`, `/triggers abort <run-id>`, or the page) ends with a
+run log record (`runs.jsonl`) that says `aborted` and `stoppedBy: "person"`. The
+slot it was running is spent: the loop runs again at its next scheduled time, not on the next
+tick. A stop is not a failure, so the run does not count toward `runs` or the failure streak. A
+one-shot loop you stop is turned off with `last error: stopped by a person; /cron run <ref> runs it
+now`, and keeps its notes. A run stopped by quitting, an upgrade or the daily budget gives its slot
+back and runs again on the next tick, as before.
+
 A job that fails three times in a row is retried on a widening gap (5 minutes, doubling, up to six
 hours) instead of at every due tick, and says so; one success clears the streak.
 
@@ -320,8 +504,8 @@ of that says whether anyone wanted what it found. So `/cron` puts two more facts
 both computed from the run log and the inbox and nothing else:
 
 ```text
- 3. cron-b91def87 "pr-watch"  enabled  */15 * * * *  [stateful]  [quiet ×12]
-    next 2026-09-15 10:15 · runs 412 · 30d: 6 findings · 6 dismissed (4 with a reason) · ~/code/acme-api
+ 3. cron-b91def87c2a04e5f9d3b6a7e1c0f4d28 "pr-watch"  */15 * * * *  [stateful]  [quiet ×12]
+    next 2026-09-15 10:15 · runs 412 · 30d: 6 findings · 6 dismissed (4 with a reason)
 ```
 
 `30d: 6 findings · 6 dismissed` is the last thirty days: findings filed, and of those still in the
@@ -337,39 +521,84 @@ watch could be hourly (`/cron set <ref> --schedule "0 * * * *"`), or that the lo
 the wrong thing. `cron_list` gives the model both facts (`signal_30d`, `quiet_streak`), so asking
 "which of my loops are worth keeping" gets an answer from the numbers rather than the names.
 
+The page's loop row shows the same numbers, only those that are not zero (`6 findings in 30 days · 6
+dismissed · quiet ×12`), and at most one suggestion, which never applies itself:
+
+- **Run hourly instead**, when the quiet streak is at least 12 and the loop runs more often than
+  hourly. An `every` loop becomes `every 1h`; a cron loop becomes `0 * * * *`. A cron loop's
+  clock restarts at the change, as `/cron set --schedule`'s does; an `every` loop's next run is
+  counted from its last run, so one that last ran more than an hour ago runs at the next tick. The
+  row says the new schedule and the next run, in the browser's local time.
+- **Pause**, when the last thirty days have at least 5 findings and 5 dismissed, and none claimed.
+
+A disabled loop, a plain job, a one-shot or a running loop gets none. Applying one changes the loop
+and writes a `cron_control_plane` audit row (`set` for the schedule, `disable` for Pause, source
+`page`). `/cron set --schedule` in a terminal writes the same `set` row (source `slash`) in
+`triggers-audit.jsonl`; an edit that leaves the schedule alone writes none. **Keep** leaves the loop as it is and
+records the answer on the job (`tuneKept`), so the same suggestion is not offered again. The
+suggestion is named with the schedule it was made for, so a loop whose schedule changes can get a
+new one.
+
+A running loop's row has **Stop this run**, with a confirm in the row; see "Stopping, removing, and
+jobs that keep failing" for what a stop does to the loop.
+
 ## When something looks wrong
 
 Every diagnostic a pi process produces is written to `logs/pi-<pid>.log` in the loops directory —
-jobs that were disabled, writes that failed, sub-agent warnings — so a loop that failed at 03:00
-still has something to read at 09:00. `/cron scheduler` prints the path. The headless host writes
-`host.log` the same way; both are rotated.
+jobs that were disabled, writes that failed, sub-agent warnings. `/cron scheduler` prints the path.
+pi-loops writes `host.log`; both logs are rotated.
 
 `PI_LOOPS_DEBUG=1` adds a line per tool call, provider retry and compaction to that log, which is
 the quickest way to tell a stuck run from a busy one.
 
 `/cron snapshot` writes a `pi_loops_snapshot` entry into the session: which MCP servers connected
-and what they exposed, the active tools, the hooks, whether this pi owns the clock, the last
-check. One is written automatically whenever that state changes. The TUI panel shows the same
-thing; the entry is for a front end that is not a terminal — the browser one in
+and what they exposed, the active tools, the hooks, whether pi-loops is running and its pid, the last
+check. One is written automatically whenever that state changes. The TUI panel is not the same:
+it lists rules, loops, the latest runs, MCP servers and hooks; it shows no pid, and shows the last
+check only when it went wrong. The entry is for a front end that is not a terminal — the browser one in
 [src/web.mjs](../src/web.mjs) reads it, and so can anything else that speaks to a session.
 
 `/triggers running` shows how long each run has been going and, for loop runs, the transcript that
 is being written right now (`pi --session <file>`), so "is it stuck or is it working" is answerable
-before the run ends. A run gets the tools the
-session that owns the clock has active (a job's `--tools` narrows that, never widens it), plus its
-own project's MCP servers, and the automation tools it calls act in its own project.
+before the run ends. A loop's run in the background gets pi's default tools, or exactly the ones its
+`--tools` names, plus its own project's MCP servers, and the automation tools it calls act in its
+own project.
 
 An unattended run refuses a corpus of dangerous commands: sudo, `curl … | sh`, writing to a block
-device, `mkfs`, `chmod 777 /`, shutdown/reboot, `git push --force` on main/master, pipes into
-`eval`, the fork bomb, and `rm -r -f` aimed at `/`, an absolute path or `$HOME`. The model is told
-why and can do the safe part.
-
-When the last pi on the machine quits, it hands the clock to a headless host (`/cron host`): a
-small `node` process with the same stores and runner that keeps loops, trigger checks and MCP
-pushes going — findings still reach the inbox — until the next pi opens and takes the clock back.
-It is started only when there is work for it: an enabled loop or rule for this machine, or an MCP
-server whose pushes inject or have rules to match. `pi-loops host status` shows what it is doing
-while it runs, and `pi-loops host abort <id>` interrupts one run (see [cli.md](cli.md)). `[host] auto = false` turns that off;
-`/cron host start` hands off on quit anyway (this pi only), `/cron host stop` ends a running host
-and cancels the hand-off. `host.log` shows what it did; a host that died is reported by the next
-pi to open. After a reboot nothing runs until a pi opens (which hands off again when it quits).
+device, `mkfs`, `chmod 777 /`, shutdown/reboot/halt as the command (also through `systemctl`; as an
+argument, `git log --grep=reboot`, they are words), `git push --force` on main/master, pipes into
+`eval`, the fork bomb, `rm -r -f` aimed at `/`, an absolute path or `$HOME`, and `pi-loops abort`,
+`stop` or `restart` as a command (after `env`, `npx`, a path or `sh -c` too, and with a verb the shell
+expands, `pi-loops $V`; `git add -A && git commit -m "pi-loops: stop retrying"` only mentions it). The model is told
+why and can do the safe part. A plain job's turn in an open window meets the same corpus, and asks
+you instead of refusing outright (see "Plain cron jobs" above).
+
+## pi-loops in the background
+
+A pi window starts the always-on `node` process on session start and each 30-second tick, and just after
+a loop or rule is added, when an enabled loop, enabled rule or relevant MCP push server exists, or a closed conversation
+has a plain job or a queued rule result. pi-loops runs stateful loops, dynamic-rule checks, MCP
+pushes, and the plain jobs of conversations no window holds. A window runs the plain jobs of the
+conversation it holds. pi-loops 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; windows do not restart it until `/pi-loops start`, or until `pi-loops` opens the page and
+says that loops and rules resume. `[host] auto = false` makes pi-loops run
+only while a pi window is open, as 0.22.8 did: the first window starts it, it leaves once the last
+window has closed, and nothing runs with none open ([configuration.md](configuration.md#host-auto));
+`PI_LOOPS_HOST=off` keeps one process from starting it. While a stop or `PI_LOOPS_HOST=off` keeps pi-loops from running,
+nothing it would run runs, and every surface says so instead of promising a schedule: the status line
+reads `loops paused: <why>`, `/cron` marks each loop (and each plain job of a closed conversation)
+`paused: <why>` with no next run, and the session-start line says this project's loops are paused. When pi-loops cannot start, it is retried after 1, 5
+and 30 minutes, with the reason in `/pi-loops status` and `host.log`. If pi-loops crashes, it is restarted by
+the next window tick, and one that crashes three times within five minutes is paused (`loops paused:
+pi-loops keeps crashing`) for half an hour, then tried again on its own; each pause that follows the
+last one at once is twice as long, a day at most, and `/pi-loops start` ends a pause at once. The error
+is the first thing `host.log` says about each crash. A loop whose runs keep stopping with pi-loops is
+parked after three such runs, each the only run in flight when pi-loops stopped, with the reason in
+`/cron`; `/cron enable <id>` tries again. A window replaces pi-loops after three failed control-socket
+probes only when pi-loops' heartbeat has stopped as well (SIGTERM, then SIGKILL after 10 seconds); a
+pi-loops process that is still ticking but does not answer on its socket is left running and reported as not
+answering, and a starting pi-loops process is not killed. pi-loops needs node: under bun it uses the `node` on
+your PATH.
+After a reboot, nothing runs until a pi opens. What pi-loops is doing is the Background view of the browser page, at `http://127.0.0.1:4173/background`;
+`pi-loops status --url` prints the page's address with the token ([cli.md](cli.md#the-background-view)).

package/docs/mcp.md

@@ -6,7 +6,9 @@ notifications and registers the servers' tools with pi.
 ## Configuration
 
 `~/.pi/agent/loops/mcp.toml`, plus `<project>/.pi/mcp.toml` for trusted projects (same server
-name → project wins). The schema:
+name → project wins). A project that has nothing of pi's own to protect is one pi never asks about,
+so there `.pi/mcp.toml` loads only once `/trust` has saved trust for it (pi applies that at its
+next start) or pi was started with `--approve`; until then the window says it ignored the file. The schema:
 
 ```toml
 [[server]]
@@ -40,8 +42,11 @@ need `_meta.pi_dedup_key` or are dropped at the source and counted. Summaries co
 method name plus bounded, redacted metadata (`notifications/resources/updated uri=…`,
 `_meta.pi_summary` capped at 200 chars) — never raw params.
 
-Delivery per server: `inject_summary` (promotion only), `inject_and_run` (user message + one turn),
-or the default: evaluation against the dynamic rules by a sub-agent.
+Delivery per server: `inject_summary` (promotion only), `inject_and_run` (a user message and one turn, queued as a request and run once the agent is idle),
+or the default: evaluation against the dynamic rules by a sub-agent. An `inject_and_run` turn is a
+scheduled turn, as a plain job's is: in an open window a command the dangerous-command policy
+refuses asks you first, with a 60-second countdown, and in the background it is refused
+([loops.md](loops.md), [configuration.md](configuration.md)).
 
 ## Tools
 
@@ -68,21 +73,24 @@ exemption and are scanned like any other command. The commands reaching this gat
 model that may have read something hostile, so an entry has to mean one command and not a foothold;
 a run that needs two shapes of a command lists both.
 
-A sub-agent shares this process's live clients rather than opening its own, so a browser tab or
-database session opened in the chat is the one the loop sees. When a run's project is not this
-process's own, that project's `.pi/mcp.toml` servers are connected on demand and lent to the run
-(only if the user has trusted that project), so a loop is not at the mercy of which window owns
-the clock; the headless host does the same. Notifications are consumed by interactive processes only; a
-sub-agent ignores what its own connection pushes: sub-agents register no notification
-hooks. A push that injects into the chat (`inject_summary` / `inject_and_run`) reaches every window
-that has the server; a push evaluated against dynamic rules is
-evaluated once per project, by the pi that owns that project's checks.
+A sub-agent shares the live clients of the process that runs it rather than opening its own. Loops
+and rule checks run in the background, so a loop sees pi-loops' clients from the user-level `mcp.toml`,
+not a browser tab or database session opened in a chat. A run's own project's `.pi/mcp.toml`
+servers are connected on demand and lent to the run (only if the user has trusted that project).
+A sub-agent ignores what its own connection pushes: sub-agents register no notification hooks. A
+push that injects into the chat (`inject_summary` / `inject_and_run`) reaches every window that
+holds a conversation and has the server; pi-loops files it in the inbox only when no window lists
+that server on its lease. A push evaluated against dynamic rules is evaluated once per project, by
+pi-loops. That includes a project's own `.pi/mcp.toml` servers: pi-loops keeps the push servers of
+every trusted project that has enabled rules connected (the first eight such projects), and a push
+from one is checked against that project's rules only. A project whose trust is revoked, or whose
+last rule is removed or disabled, has its servers stopped within a minute.
 
 A repeated `[[server]]` name replaces the earlier entry (a diagnostic says so); the project file is
 `<project>/.pi/mcp.toml`.
 A machine-wide dedup window (`~/.pi/agent/loops/dedup.json`, 5 minutes) makes each push count once
-no matter how many pi windows are open, and results are promoted only into a chat that belongs to
-the rule's project (otherwise they go to the inbox). Crashed stdio servers are reconnected with
+no matter how many pi windows are open, and a rule's result goes to the conversation that created
+it (see [triggers.md](triggers.md)). Crashed stdio servers are reconnected with
 exponential backoff, 20 attempts by default, each distinct error reported once (rather than marking them
 disconnected). `/triggers sources` lists MCP servers first, then the cron hook, then the dynamic
 checker, in registration order; a stdio server's last stderr line is shown as `stderr:`

package/docs/recipes.md

@@ -84,6 +84,11 @@ answered. `/recipe list` shows them in those two groups.
    `/recipe list` and `/recipe remove` can find them. Each prompt is a pointer:
    `Read .agents/skills/issue-loop/triage.md and do what it says for this repository.` The
    procedure is read fresh on every run; edit the file and the next run follows the edit.
+   The jobs belong to the conversation that ran `/recipe add`, which is told of their findings. A
+   conversation pi has not saved yet cannot own one: pi writes a conversation's file only once it
+   holds a message, and `/recipe add` is none (a starter's **Add** in a new page conversation is the
+   usual case). Then the jobs belong to the project, the install says so, and a finding runs in the
+   conversation it is claimed from; no conversation counts it as its own.
 
 `pi-loops recipe list|show|add` in a shell does step 6 and nothing after: the setup script and the
 jobs are things a person should see before they exist, and only the pi inside `/recipe add` can show
@@ -154,6 +159,7 @@ and should be read before it is installed).
 ```toml
 name = "issue-loop"                 # lowercase, digits, dashes; also the install directory
 summary = "one line"
+line = "at most twelve words"         # optional; the page's starter card and both recipe lists show it whole, else the summary
 tier = "advanced"                   # optional; "starter" reads and files findings, "advanced" (the default) writes somewhere
 useful_when = ["one sentence"]      # optional; the situations it is for, printed by `show`
 needs_tracker = true                # gate on docs/agents/issue-tracker.md