@alphacoder-v0/pi-loops 0.19.3 → 0.22.0

package/docs/loops.md

@@ -65,21 +65,33 @@ transcript when the run finishes. Prompts are capped at 8 KB.
 
 ## The inbox
 
-Global JSONL, shared by every session and project, with a stable record shape (`id` = `inb-<32 hex>`,
-`created_at`, `source` = `cron:<job>`, `text`, `trace_id` = the run id, `session_id`, `status`
-`new → claimed | dismissed`) plus pi-loops' `job_id`, `cwd`, `claimed_by`, `verified`,
-`verified_reason`. Job ids are `cron-<32 hex>`; prefixes, names and list numbers resolve.
+Global JSONL, shared by every session and project. Each line is one finding in the shape
+[CONTRACT.md](../CONTRACT.md) §2.2 fixes, followed by pi-loops' own fields. Job ids are
+`cron-<32 hex>`; prefixes, names and list numbers resolve.
 
 ```text
-/inbox                 Inbox (<project>, N new, 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>, <source>, <created_at>)"
 /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:
                        "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>  /inbox clear [--all]
+/inbox dismiss <n|id> [reason]   mark dismissed; the reason, if you give one, is shown to the loop's next run
+/inbox clear [--all]
 ```
 
+A dismiss with words after the number — `/inbox dismiss 2 that file is generated, ignore it` — is
+the one way a person talks back to a loop. The reason is stored on the entry and put in front of
+the **next run of the loop that reported it**, between its notes and its task, in a `[dismissed]`
+block that says not to report the finding again unless what it describes has changed, and to carry
+into the notes whatever it needs to remember that. It is shown to that one run only: a loop has
+nothing but its notes between runs, and a second memory the notes cap does not bound would be one
+the loop could not edit or forget. Up to eight reasons per run, the newest kept. A bare
+`/inbox dismiss 2` and `/inbox clear` stay silent, as before — "not interesting" is not something
+the next run can act on. `/inbox all` shows the reason on the dismissed line. For a dismiss,
+`--all` counts only before the reason begins (`/inbox dismiss --all 3 …` or `/inbox dismiss 3 --all …`);
+a reason that mentions `--all` in passing does not re-number the list you were looking at.
+
 The file is machine-wide because loops are; triage is not. `/inbox` lists this project's findings
 the way `/cron` lists its jobs, names the project on every line, and says how many are waiting
 elsewhere; `--all` lifts the filter. Numbers are the numbers on screen — `/inbox claim 3` claims
@@ -88,8 +100,17 @@ 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.
 
-Corrupt lines are skipped on read and never deleted. The footer shows `Inbox: N new` (the whole
-machine, as the badge always has) and `N job(s) failing (<worst> ×<count>)` once a loop has failed
+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
+appended, and the entry carries `kind: "checkpoint"` from then on; news carries nothing. `/inbox`
+lists checkpoints first, marked `⚑`, and says how many there are in its header (`3 new, 1 needs a
+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
 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
@@ -167,7 +188,8 @@ changed is worth one look at `/cron state <id>`.
 ### Daylight saving
 
 Local time means the clock does what the clock does, and twice a year it does something strange.
-Measured, not assumed (`America/New_York`, 2026):
+Measured, not assumed (`America/New_York`, 2026) — and pinned by `test/dst.test.ts`, which sets the
+zone it needs rather than reading the one the machine happens to have.
 
 | | what happens |
 |---|---|
@@ -285,6 +307,30 @@ is gone — `--all` every project's, `--purge` also the loop state left behind b
 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.
 
+## Was it worth running
+
+A loop was judged, until now, by whether it ran: `runs 42`, a last error, the failing badge. None
+of that says whether anyone wanted what it found. So `/cron` puts two more facts on a loop's lines,
+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
+```
+
+`30d: 6 findings · 6 dismissed` is the last thirty days: findings filed, and of those still in the
+inbox, how many a person claimed and how many they dismissed (with how many reasons). A loop whose
+findings are all dismissed is noise at any price; one whose findings are all claimed is the one to
+keep. `/cron cost` shows the same counts beside each job's spend, for its own window, so
+`$0.410  28 run(s)  pr-watch  —  6 findings · 6 dismissed` is a line that answers itself.
+
+`[quiet ×12]` means the twelve newest runs found nothing, whatever the window. It is not a fault —
+a watch on a quiet thing is supposed to be quiet — and pi-loops does not slow the job down for it:
+the schedule is the schedule. It is the number to read before deciding that a fifteen-minute
+watch could be hourly (`/cron set <ref> --schedule "0 * * * *"`), or that the loop is looking at
+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.
+
 ## When something looks wrong
 
 Every diagnostic a pi process produces is written to `logs/pi-<pid>.log` in the loops directory —

package/docs/recipes.md

@@ -14,16 +14,21 @@ anything a person could not have typed.
 /recipe remove issue-loop  its jobs go; the files stay unless you say --purge
 ```
 
-Two recipes ship in this version, and the shape is meant to be copied:
-
-| recipe | jobs | what it runs | levels |
-|---|---|---|---|
-| [issue-loop](../recipes/issue-loop/) | `issue-triage` every 30 min, `issue-implement` every 30 min offset | the issue tracker as a state machine: triage into agent briefs, build accepted issues in a worktree, open pull requests | `propose`, `act` |
-| [autoresearch](../recipes/autoresearch/) | `autoresearch` every hour, with `--verify` | one experiment per run against a contract you wrote, a ledger of every attempt, promotion only on held-out evidence | `propose`, `act` |
-
-`changelog-draft` (a nightly changelog entry and version proposal) is packaged with its playbook
-and manifest but is still the release-side half of the issue loop; it and four more — a daily
-digest, a pull-request watch, a CI sweeper, an ecosystem scan — are the next batch.
+Eight recipes ship, and the shape is meant to be copied. Three are **starters** — they read, and
+file findings, and are the ones to install first; the rest are **advanced** — they write to a
+worktree, a tracker or a pull request, and want their playbooks read before the level question is
+answered. `/recipe list` shows them in those two groups.
+
+| recipe | tier | jobs | what it runs | levels |
+|---|---|---|---|---|
+| [issue-loop](../recipes/issue-loop/) | advanced | `issue-triage` every 30 min, `issue-implement` every 30 min offset | the issue tracker as a state machine: triage into agent briefs, build accepted issues in a worktree, open pull requests | `propose`, `act` |
+| [autoresearch](../recipes/autoresearch/) | advanced | `autoresearch` every hour, with `--verify` | one experiment per run against a contract you wrote, a ledger of every attempt, promotion only on held-out evidence | `propose`, `act` |
+| [daily-digest](../recipes/daily-digest/) | starter | `daily-digest` at 09:00 | one finding saying what needs a look today — open items, a red CI, a loop that keeps failing — or none | `report` |
+| [pr-watch](../recipes/pr-watch/) | starter | `pr-watch` every 15 min | the open pull requests, and only what changed about them: a red check, a conflict, a review waiting, an author who answered | `report`, `propose` |
+| [ci-sweeper](../recipes/ci-sweeper/) | advanced | `ci-sweeper` every 15 min, 40-minute timeout | a red default branch reported, or repaired in a worktree and put up as a pull request; the same failure twice unfixed is a stop | `report`, `propose` |
+| [changelog-draft](../recipes/changelog-draft/) | starter | `changelog-draft` weekdays at 18:00 | when the default branch is ahead of the last tag, the changelog entry and a version, drafted — or put in a release pull request | `report`, `propose` |
+| [ecosystem](../recipes/ecosystem/) | advanced | `ecosystem` Mondays at 10:00 | who uses or forks this project, and the one reply or upstream invitation worth sending, drafted as a finding a person sends | `propose` |
+| [deps-sweeper](../recipes/deps-sweeper/) | advanced | `deps-sweeper` Mondays at 08:00, 40-minute timeout | the advisories and major-version gaps not already in its notes; under `propose`, the patch and minor updates applied in a worktree, checked, and put up as one pull request | `report`, `propose` |
 
 ## What `/recipe add` does, in order
 
@@ -42,28 +47,45 @@ digest, a pull-request watch, a CI sweeper, an ecosystem scan — are the next b
    `--level act` skips it.
 3. **A name check.** A job with the same name already in `jobs.json` stops the install and says
    which recipe or `/cron add` it came from.
-4. **The confirmation.** Every file that will be written and where, every `/cron add` line that
-   will be run, the budget hint. The setup script is printed into the transcript first, whole and
+4. **The preflight.** What the project has and lacks for this recipe's runs, checked now and
+   printed in the confirmation under *Before the first run* — reported, never enforced, so a
+   missing `gh` login is a line you read tonight rather than an empty inbox tomorrow morning.
+   A manifest names its checks (`needs`, and `needs_propose` for the levels that push and open
+   pull requests); a recipe that reads the tracker is checked for `gh` only when
+   `docs/agents/issue-tracker.md` uses it, so a local Markdown tracker asks for nothing.
+
+   | check | what is looked at |
+   |---|---|
+   | `gh` | `gh` on the PATH and `gh auth status` succeeding (10 seconds, then "could not check") |
+   | `git-remote` | `git remote get-url origin` |
+   | `ci-workflows` | a `.yml` under `.github/workflows/` |
+   | `lockfile` | one of the package managers' lockfiles at the root |
+   | `tracker-github` | the tracker description names GitHub; a local one has no pull requests to watch |
+
+   `/recipe show` runs the same checks at the recipe's highest level.
+5. **The confirmation.** Every file that will be written and where, what the playbooks forbid a
+   run to do (each playbook's `## Never` section, the same lines `/recipe show` prints), every
+   `/cron add` line that will be run, the budget hint, the preflight. The setup script is printed into the transcript first, whole and
    as written — it will run with this session's environment, and a dialog clips what does not fit,
    so it is not put in one; a script too long to show is not run at all. A recipe installed from a path
    rather than by name is flagged as not shipped with pi-loops, with the playbooks to read first.
    Nothing has happened yet.
-5. **The install.** The playbooks are copied to `.agents/skills/<recipe>/`, with an untouched copy of each
+6. **The install.** The playbooks are copied to `.agents/skills/<recipe>/`, with an untouched copy of each
    under `.orig/` and a `.recipe.json` record (version, level, when). The directory (and the
    tracker description) is listed in `.git/info/exclude` — git's own place for a rule that belongs to one clone — so the repository
    is not touched and nothing shows in `git status`. pi discovers the copies as `/skill:` commands,
    which is how a person runs one step by hand when the loop's judgement needs checking — once the
    project is trusted: a directory that gains `.agents/skills/` is one pi asks about at its next
    start (`/trust`). The loops do not depend on that; they read the files by path.
-6. **The setup script**, if any, runs once in the project (issue-loop's creates the tracker's
+7. **The setup script**, if any, runs once in the project (issue-loop's creates the tracker's
    labels; it is idempotent). A failure stops before any job is created and prints the output; the
    files stay in place and `/recipe add` again resumes.
-7. **The jobs**, through the same code path as `/cron add`, each carrying `recipe: "<name>"` so
+8. **The jobs**, through the same code path as `/cron add`, each carrying `recipe: "<name>"` so
    `/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.
 
-`pi-loops recipe list|show|add` in a shell does steps 5 and nothing after: the setup script and the
+`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
 them. It leaves the files in place and says so; `/recipe add` then finds nothing to copy.
 
@@ -84,6 +106,29 @@ were there before recipes: the [dangerous-command policy](loops.md#when-somethin
 night ([loops.md](loops.md#what-it-costs-and-capping-it)); each recipe's `show` says roughly what
 its default schedules cost.
 
+## Checkpoints
+
+A checkpoint is a finding that asks a person to decide, and at three in the morning it is read by
+someone who has not seen the tracker since yesterday. So every one of them, in every packaged
+playbook, says the same three things in one line: **the decision**, **what waits on it**, and
+**what happens if nobody acts**.
+
+```text
+#14 brief posted — recommend ready-for-agent (bug, reproduced by npm test) · waits: the implement loop skips it until labeled · if not: stays needs-triage, no reminder
+promote research/007-argpartition: dev 1.0 → 3.1, held-out 1.0 → 2.8 · waits: your merge · if not: the branch and worktree stay, later runs build on it as the best kept
+CI red on main: test/web.test.ts — two fixes did not hold · waits: a person · if not: this signature is not retried
+```
+
+The shape is also how the inbox tells a checkpoint from news: ` · waits:` marks the entry, it is
+listed first with a `⚑`, and `/inbox` counts it apart (`3 new, 1 needs a decision`;
+[loops.md](loops.md#the-inbox)).
+
+The third clause is the one that matters overnight. A loop that waits for an answer says so and
+keeps going with everything the answer does not block; a loop that would do something on silence
+(retry, re-propose when the head moves, keep building on a kept branch) says that instead, so a
+person who decides to do nothing knows what nothing buys. Findings that are only news — a merged
+pull request, a red check, a digest line — are not checkpoints and do not carry the clauses.
+
 ## Editing, updating, removing
 
 The copies are yours. `/recipe update <name>` after a pi-loops upgrade is a three-way merge of the
@@ -108,7 +153,11 @@ and should be read before it is installed).
 ```toml
 name = "issue-loop"                 # lowercase, digits, dashes; also the install directory
 summary = "one line"
+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
+needs = ["gh", "ci-workflows"]      # optional; preflight checks at every level (gh, git-remote, ci-workflows, lockfile, tracker-github)
+needs_propose = ["git-remote"]      # optional; the same, added at propose and act
 levels = ["propose", "act"]         # which positions of the dial the playbooks understand
 setup = "labels.sh"                 # optional; shown, then run once, before the jobs exist
 files = ["RESEARCH.template.md"]    # optional; copied beside the playbooks unchanged
@@ -126,7 +175,9 @@ same parser: a bad schedule, a `--timeout` that is not a duration, an expression
 matches, is refused when the manifest is read, not on the first run. A playbook is Markdown with
 pi's skill frontmatter (`name`, `description`) and an `Autonomy:` line the wizard will set; the
 rest is what a run should do, written for a sub-agent that has only its notes, the files, and the
-tools. The two packaged recipes are the reference for the voice.
+tools. End it with a `## Never` section: the lines under it are what `/recipe show` and the
+install confirmation print as the run's safety envelope, and every packaged playbook has one. The
+packaged recipes are the reference for the voice.
 
 ---
 
@@ -194,12 +245,78 @@ mid-implementation resumes from its branch and notes; a check command failing tw
 is a block, not a third attempt; the loop and you editing the same issue is settled by the
 tracker, which wins.
 
+With the local Markdown tracker the shape is the same and the pull request is not there: the
+implement loop pushes its branch (or leaves it local), sets the item to `in-review` and files a
+finding naming the branch. Requesting changes is a comment under the item's `## Comments` and the
+status set back to `agent-working`; merging is `git merge` by a person, the status set to `done`
+and the file moved to `closed/`. The setup script creates no labels there — it says so and exits —
+and does the same when `gh` is missing or not logged in, so the install goes through and the
+first run reports what it cannot do.
+
 Specific to this repository: the labels are on
 [github.com/alphacoder-v0/pi-loops](https://github.com/alphacoder-v0/pi-loops/labels), the check
 command is `npm run ci`, and a release needs a one-time password — so the release side can only
 propose, which is what `changelog-draft` does everywhere.
 
-## autoresearch
+## daily-digest
+
+One job at nine, one level. It reads the tracker, the latest run on the default branch, the last
+day's commits, and the automation's own health — a loop that failed its last two runs, a finding
+that has sat in the inbox for three days — and files **one** finding, the day first, then a line
+per thing that needs a look. A quiet day files nothing, and a thing reported yesterday and
+unchanged is not repeated: the notes carry a watermark and yesterday's lines. The loop writes
+nowhere but the inbox.
+
+## pr-watch
+
+Every fifteen minutes, each open pull request gets one state — `green`, `red-check`, `conflict`,
+`awaiting-review`, `changes-requested`, `answered` — and a finding is filed only when a state
+changed since the last run, or a stall has lasted another whole day. Under `propose` the loop may
+leave one comment on a pull request that has waited on the same person for more than two days,
+once per stall, remembered in its notes. It never merges, approves, rebases or pushes.
+
+## ci-sweeper
+
+Every fifteen minutes, the latest run on the default branch. Green: nothing. Red: a **failure
+signature** (job, step, first error line, normalised) is the memory — under `report` it is one
+finding per signature and one more when the branch is green again; under `propose` the loop
+reproduces it in a worktree, fixes the cause, runs the project's check command and opens a pull
+request, and the same signature attempted twice without a green check is a stop with a finding
+that says so. A test is never skipped or deleted to get to green, and the workflow file is never
+edited to make it pass.
+
+## changelog-draft
+
+Weekdays at six, if the default branch is ahead of the last tag by anything but chores: the
+changelog entry in the project's own style and a version picked the way its history picks them.
+Under `report` the draft is the finding; under `propose` it is also a branch, the entry written
+in, the version bumped, and a pull request whose link leads the finding — a person merges it and
+tags. Tagging and publishing are never the loop's: they need a key, a one-time password and a
+decision.
+
+## ecosystem
+
+Mondays, once. It searches for repositories that use, mention or fork this project, sorts them
+into integrations, derivatives, mentions and noise, and for each integration or derivative looks
+for **one** thing worth a word: a problem they hit that is fixed upstream, a fork commit worth
+bringing back, an unanswered question. Each draft is a finding with the text ready to post;
+claiming the finding is what sends it, as the person, from their chat. The loop itself never
+posts, comments or opens anything anywhere, which is why its only level is `propose`.
+
+## deps-sweeper
+
+Mondays at eight. The loop finds the project's package manager from its lockfile and runs the
+audit and outdated commands that manager has. The **advisory id** and the **package at a major
+version** are the memory: under `report` each advisory not in the notes is one finding, each direct
+dependency a whole major behind is one finding once, and a finding is repeated only when it
+changes — an advisory fixed, a major that moved again. Under `propose` the loop also applies the
+patch and minor updates the manager offers, in a worktree, as **one** pull request per run: the
+project's check command has to be green first, a package on the playbook's deny list is never
+touched, a major is never applied (it is a finding, and a person's decision), and the same package
+attempted twice without a green check is a stop with a finding that says so. The lockfile is
+only ever written by the package manager, never by hand. Merging stays with a person at every level.
+
+## Another tracker
 
 The shape Karpathy's autoresearch and Arbor made familiar, without a kernel: a **research
 contract** a person writes, a **ledger** of every attempt including the failed ones, one isolated
@@ -221,6 +338,11 @@ was tuning against.
   better: `retired`, worktree removed, branch deleted, no finding — a retired experiment is the
   normal outcome and the row is what matters. Better on dev: measure on held-out; a dev-only gain
   is `retired` too, with that note.
+- **A streak of retired rows is the ledger's own checkpoint.** Five in a row since the last kept
+  row files one finding asking whether the contract's directions, metric or budget are wrong, and
+  the loop keeps going only in idea classes it has not tried; ten in a row stops the loop until
+  `RESEARCH.md` changes (its hash is in the notes). An hourly loop in the wrong search space is the
+  expensive failure, and the person who wrote the contract is the one who can fix it.
 - **Promotion** is the checkpoint. Under `propose` the finding names the branch and both numbers
   and a person merges; under `act` the loop merges into the checkout's current branch and the
   finding says so. The job runs with `--verify`, and the playbook's *For the checker* section tells

package/docs/session-archive.md

@@ -15,7 +15,7 @@ pi-session-<first 16 chars of the id>.pisession   uncompressed ustar, mode 0600,
 
 ```text
 /session-export [path] [--exclude-triggers]
-/session-import <path> [--activate-triggers=on|off] [--cwd <dir>] [--resume]
+/session-import <path> [--activate-triggers=off|ask|on] [--cwd <dir>] [--resume]
 ```
 
 Both commands print a sensitivity warning before doing anything, success or failure.
@@ -24,8 +24,13 @@ the source machine's parent-session pointer dropped)
 into this project's session directory and rewrites the sidecars: automation disabled
 unless `--activate-triggers=on`, running markers / errors / overlap counters cleared, ids
 regenerated when they collide with existing ones (loop state follows the new id), non-stateful jobs
-rebound to the imported session. Afterwards you are asked once whether to re-enable what was
-enabled in the source. `--resume` switches to the imported session; otherwise `pi --session <path>`.
+rebound to the imported session. `--resume` switches to the imported session; otherwise
+`pi --session <path>`.
+
+`--activate-triggers=off|ask|on` decides what happens to the automation the archive carries, and
+means the same thing here as in `pi-loops import`. The default is `ask`: the import leaves it
+disabled and then asks once, where there is a terminal or a UI to ask in, whether to enable what
+was enabled in the source. `off` never asks; `on` activates it as part of the import.
 
 Validation: manifest schema, session checksum, path traversal, and size caps (session 50 MiB,
 sidecars 2 MiB). Every sidecar is validated before the session file is written, and store writes

package/docs/web-ui-parity.md

@@ -17,7 +17,9 @@ weaker, and worth converting whenever one of them breaks.
 - [x] Enter does nothing while an input method is composing — typing Chinese, Japanese or Korean
       means Enter picks a candidate, not "send". `test/web-page.test.ts`: *Enter while an input
       method is mid-word does not send*.
-- [x] Submitting while a turn is running queues instead of racing it, the way the TUI does.
+- [x] Submitting while a turn is running queues instead of racing it, the way the TUI does — and a
+      slash command typed into it runs while the turn runs, as it does in the terminal.
+      `test/web.test.ts`: *a command typed while a turn is running reaches pi as one it can run*.
 - [x] The queue is visible and can be cleared.
 - [x] Abort stops the current turn.
 - [x] Busy, queued count, and "pi exited" are all visible without opening a terminal.
@@ -49,6 +51,14 @@ weaker, and worth converting whenever one of them breaks.
 - [x] A tap on a composer button lands on that button, even with a soft keyboard open — tapping it
       blurs the box, which dismisses the keyboard, which moves everything.
       `test/web-page.test.ts`: *a phone's soft keyboard cannot steal the tap on send*.
+- [x] What is in the composer survives a reload, and belongs to the tab that typed it: the header's
+      reload button, the stale-page banner and a phone that discards a backgrounded tab all come
+      back to the same text, and a second tab of the same address keeps its own.
+      `test/web-page.test.ts`: *a reload keeps what is in the composer, in that tab only*.
+- [x] The composer grows with what is typed into it, up to the ceiling the stylesheet declares, and
+      comes back down when the text goes or is sent — a multi-line prompt is written and read at its
+      own height rather than through a one-line slot. `test/web-page.test.ts`: *the composer grows
+      with a multi-line prompt, and shrinks again*.
 
 ## What the feed shows
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.19.3",
+  "version": "0.22.0",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "recipes",
     "README.md",
     "README.zh-CN.md",
+    "CONTRACT.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -45,14 +46,17 @@
     "publishedToNpm": true
   },
   "scripts": {
-    "ci": "npm run typecheck && npm run lint && npm run check:scripts && npm run check:docs && npm test",
+    "ci": "npm run typecheck && npm run lint && npm run check:scripts && npm run check:docs && npm test && npm run check:downstream && npm run check:contract",
     "typecheck": "node scripts/typecheck.mjs",
     "lint": "node scripts/lint.mjs",
     "check:docs": "node scripts/check-docs.mjs",
+    "check:downstream": "sh test/downstream/run.sh",
+    "check:contract": "sh test/contract/run.sh",
     "test": "node --import ./src/register-pi.mjs --test test/*.test.ts",
     "check:scripts": "node --check src/web.mjs && node --check src/cli-entry.mjs && node --check src/host-entry.mjs && node --check src/ts-entry.mjs && node --check src/pi-resolver.mjs && node --check src/register-pi.mjs && node --check examples/mcp-notify-server.mjs"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"

package/recipes/_tracker/issue-tracker-local.md

@@ -29,7 +29,9 @@ checkpoint is a finding in the inbox that names the branch.
 - **Change state**: edit the `**Status:**` line — exactly one state
 - **Claim**: set `**Status:** agent-working` and add `**Assignee:** <who>`, and commit that edit on the work branch before any other work
 - **Close**: set the status to `wontfix` or `done` and move the file to `.scratch/issues/closed/`
-- **Review**: push the branch (or leave it local) and file a finding that names the branch and the item; a person merges with git
+- **Review**: push the branch (or leave it local), set `**Status:** in-review`, and file a finding that names the branch and the item — `in-review` here means the branch exists and the finding has been filed; there is no pull request
+- **Request changes** (a person): append a comment under `## Comments` saying what to change and set `**Status:** agent-working`; the implement loop reads comments newer than the timestamp in its notes and addresses them
+- **Merge** (a person): merge the branch with git, set `**Status:** done`, and move the file to `closed/`; the loop's housekeeping removes the worktree on its next run
 
 ## State vocabulary
 

package/recipes/autoresearch/experiment.md

@@ -42,6 +42,20 @@ before anything slow. Your final reply is read by a program.
    trying first" and "not to try" lists bound the space. Write one sentence: what you will change
    and why it should move the metric. Append the row now with status `running` — a crash leaves a
    record, not a mystery.
+
+   **First, look back.** Count the `retired` rows since the last `kept` or `promoted` one (or the
+   baseline). A streak is the ledger telling you the space is wrong, not that the next idea is:
+   - **5 in a row**, and you have not said so since the streak began (your notes' `stalled-at`):
+     one finding — `autoresearch: 5 retired in a row (<the idea classes tried>) · waits: a
+     change to RESEARCH.md's directions, metric or budget · if not: I keep trying, but only in
+     classes not yet tried` — and choose this run's hypothesis outside every class in your notes'
+     `tried` line.
+   - **10 in a row**: stop choosing. One finding — `autoresearch: 10 retired in a row, stopping
+     until RESEARCH.md changes · waits: an edit to the contract · if not: nothing runs; the ledger
+     is at <path>` — write the notes with the contract's hash, and end the run. A later run whose
+     `RESEARCH.md` hash differs from the notes' starts the count again at zero; one whose hash is
+     the same files nothing and stops again.
+   A `kept` or `promoted` row resets the streak.
 6. **Branch.** `git worktree add <worktrees>/<NNN> -b research/<NNN>-<slug> <current branch>`
    (create the worktrees directory first if it is missing).
    Change only the editable files. Commit in the worktree before measuring.
@@ -53,7 +67,8 @@ before anything slow. Your final reply is read by a program.
      contract's promotion rule → status `kept` and go to 8; otherwise `retired` with note
      `dev-only gain` (the classic overfit; still negative evidence) and remove the worktree.
 8. **Promote.** Under `propose`: one finding —
-   `promote research/<NNN>-<slug>: dev <x> → <y>, held-out <a> → <b> (<hypothesis>)` — and leave
+   `promote research/<NNN>-<slug>: dev <x> → <y>, held-out <a> → <b> (<hypothesis>) · waits: your
+   merge · if not: branch and worktree stay; later runs build on it as the best kept` — and leave
    the worktree and branch for the person. Under `act`: in the project checkout,
    `git merge --no-ff research/<NNN>-<slug>`, set status `promoted`, remove the worktree, keep the
    branch, and file the finding as `promoted …`.
@@ -68,15 +83,24 @@ A second sub-agent reviews the findings of this run before they reach the inbox.
 or `promoted` finding: check out the named branch in its worktree (or the merge in the checkout),
 run the contract's **held-out** command yourself, and keep the finding only if the number you get
 satisfies the promotion rule against the ledger's best row; drop it with the number otherwise. A
-`no RESEARCH.md` or protected-file finding is kept if the file state is as described.
+`no RESEARCH.md` or protected-file finding is kept if the file state is as described; a `retired
+in a row` finding is kept if the ledger shows the streak it names.
 
 ## Notes for the next run
 
 `best=<id> <heldout>` · `next=<NNN>` · `in-progress: <id> worktree=<path>` or `none` ·
-`tried: <one line per idea class you have exhausted>`. Under 2000 characters; the ledger holds
-the rest.
+`tried: <one line per idea class you have exhausted>` · `stalled-at=<row id the 5-streak finding
+was filed at, or none>` · `contract=<sha256 of RESEARCH.md>`. Under 2000 characters; the ledger
+holds the rest.
 
 ## Inbox
 
-Only: a promotion (proposed or done), a contract problem, an eval that cannot run. Never a retired
-experiment — the ledger is where those live, and a person reads the ledger when they want to.
+Only: a promotion (proposed or done), a contract problem, an eval that cannot run, a streak of
+retired experiments long enough to question the contract. Never a single retired experiment — the
+ledger is where those live, and a person reads the ledger when they want to.
+
+## Never
+
+Never write the contract (`RESEARCH.md`) yourself, never edit a protected file. Never push; never
+merge under `propose`; never run two experiments in one run. Never retry an eval that failed for
+a reason that is not your change — that is one finding and a stop.

package/recipes/autoresearch/recipe.toml

@@ -2,6 +2,8 @@
 # a ledger, a checker re-measures on held-out data before anything is proposed. docs/recipes.md.
 name = "autoresearch"
 summary = "One experiment per run against a research contract you wrote; a ledger of what was tried; promotion only on held-out evidence."
+tier = "advanced"
+useful_when = ["You have a metric a script can print and a search space wider than your evenings.", "You want every attempt in a ledger, the failed ones included."]
 needs_tracker = false
 levels = ["propose", "act"]
 files = ["RESEARCH.template.md", "example/RESEARCH.md", "example/solution.py", "example/eval.py", "example/eval.sh"]

package/recipes/changelog-draft/recipe.toml

@@ -1,7 +1,12 @@
 name = "changelog-draft"
 summary = "When the default branch is ahead of the last tag, draft the changelog entry and propose a version; a person tags."
+tier = "starter"
+useful_when = ["Releases wait on someone finding an evening to write the entry.", "You want the version and the entry proposed from the commits, and to tag it yourself."]
 needs_tracker = false
-levels = ["report"]
+levels = ["report", "propose"]
+needs = ["git-remote"]
+needs_propose = ["gh"]
+budget_hint_usd = 1
 
 [[job]]
 name = "changelog-draft"

package/recipes/changelog-draft/release.md

@@ -7,7 +7,13 @@ description: One run of the release loop. Compares the default branch with the l
 
 Autonomy: report
 
-You are the release loop. You **propose**; a person releases. Tagging and publishing need things
+The line above is the installed level.
+- `report`: the draft goes in the inbox line.
+- `propose`: the draft goes into a pull request too — a branch, the changelog entry written in,
+  the version bumped where the project keeps it — and the inbox line carries the link. A person
+  merges it and tags.
+
+You are the release loop. You propose; a person releases. Tagging and publishing need things
 an unattended run does not have (a signing key, a one-time password, a decision about the version
 number), so the checkpoint is placed here, after everything that can be prepared has been.
 
@@ -28,8 +34,22 @@ number), so the checkpoint is placed here, after everything that can be prepared
    version the way the project's history does (a `feat:` bumps the minor of a 0.x project; only
    fixes bump the patch). Do not edit any file; the draft goes in the inbox line.
 
-4. Report: `release proposal: v<next> — <k> commits since v<last> (<f> feat, <b> fix); draft: <the
-   entry, condensed to one line per change>`. Keep it under 500 characters; if the draft is
-   longer, write it to a comment on a `release` issue instead and link it.
+4. Under `propose`, before reporting: `git worktree add ../<repo>-release/<next> -b release/<next>
+   origin/<default branch>`, write the entry at the top of `CHANGELOG.md` in the project's style,
+   bump the version wherever the project keeps it (`package.json`, and any file the project's own
+   checks tie to it — run those checks), commit `chore: release <next>`, push `-u`, open a pull
+   request whose body starts with a line saying it was generated by AI and lists the commits.
+   If a release pull request of yours is already open for an older head, update its branch
+   instead of opening a second one. Never tag, never publish, never push the default branch.
+
+5. Report: `release proposal: v<next> — <k> commits since v<last> (<f> feat, <b> fix); draft: <the
+   entry, condensed to one line per change> · waits: your tag · if not: re-proposed when the head
+   moves, not before` — under `propose`, `PR <url>` first and the draft after. Keep it under 500
+   characters; if the draft is longer, the pull request has it whole and the finding says so.
+
+Notes: `last-reported-head=<sha> last-tag=<tag> open-pr=<url or none>`.
+
+## Never
 
-Notes: `last-reported-head=<sha> last-tag=<tag>`.
+Never tag, never publish, never push the default branch. Never open a second release pull
+request while one of yours is open — update its branch instead.

package/recipes/ci-sweeper/README.md

@@ -0,0 +1,9 @@
+# ci-sweeper — a red default branch, reported or repaired
+
+| file | what it is |
+|---|---|
+| [recipe.toml](recipe.toml) | one job every 15 minutes, 40-minute timeout, `report` or `propose` |
+| [sweep.md](sweep.md) | the playbook: latest run → failure signature → finding, or worktree, fix, checks, pull request |
+
+The failure signature is the memory: the same red reported once, the same failure attempted at
+most twice, and a test never skipped or deleted to get to green.

package/recipes/ci-sweeper/recipe.toml

@@ -0,0 +1,16 @@
+# ci-sweeper: a red default branch gets a finding, or a fix in a worktree and a pull request. docs/recipes.md.
+name = "ci-sweeper"
+summary = "When the default branch's checks go red, says so — or, at propose, reproduces the failure in a worktree, fixes it, and opens the pull request; twice failing to fix the same failure is a stop."
+tier = "advanced"
+useful_when = ["The default branch goes red and every open pull request looks red with it.", "The failures are the boring kind: a flaky assertion, a renamed fixture, a dependency that moved."]
+needs_tracker = false
+levels = ["report", "propose"]
+needs = ["gh", "ci-workflows"]
+needs_propose = ["git-remote"]
+budget_hint_usd = 5
+
+[[job]]
+name = "ci-sweeper"
+schedule = "*/15 * * * *"
+playbook = "sweep.md"
+timeout = "40m"