@alphacoder-v0/pi-loops 0.20.0 → 0.22.1

package/CHANGELOG.md

@@ -3,6 +3,162 @@
 All notable changes to pi-loops are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow SemVer.
 
+## [Unreleased]
+
+## [0.22.1] - 2026-09-16
+
+### Fixed
+- **The launcher survives the package being installed by the other route.** The `sh` script
+  `install-launcher` writes named one entry file and nothing else, so `pi install npm:…` over a
+  `git:` copy — or the reverse — left every `pi-loops` ending in Node's `Cannot find module
+  …/src/cli-entry.mjs` stack trace, `pi-loops upgrade` included; the comment claiming it "survives
+  the package moving" was the only thing that did. It now carries both places pi installs this
+  package to (`npm/node_modules/<name>` and `git/<host>/<owner>/<repo>`, under the agent directory
+  it was written with) as literal paths and runs the first one that is there, falls back to the
+  `node` on `PATH` when the node it recorded has gone too, and when no copy is in any of them says
+  so in one line — write the launcher again with `install-launcher` — instead of a stack trace.
+
+## [0.22.0] - 2026-09-16
+
+### Added
+- **One shape for a finding.** A line of `inbox.jsonl` is now the very object `pi-loops inbox
+  --json` prints — the ten fields of [docs/downstream.md](docs/downstream.md) §3, in their order,
+  under their names — instead of a third spelling of the same record (`trace_id` for the run id,
+  camelCase in memory, keys left out when they were empty). The entry in memory has those names
+  too, so both translations are a copy and a subset: nothing is renamed on the way in or out, and
+  a field that has to be added is added in one place. Lines written by earlier versions are still
+  read, and rewritten in the new shape the next time a claim or a dismiss touches them. `kind` is
+  now on every finding (`news` when the text is not a checkpoint) rather than only on checkpoints.
+  Keeping pi-loops' own fields — `job_id`, `session_id`, `claimed_by`, `verified_reason`,
+  `dismissed_at` — on the same line after the ten is this version's choice, not something the
+  interface asks for: they are private state and a program that reads them is reading what it was
+  told not to.
+
+### Changed
+- **The contract is written once.** `CONTRACT.md` §2 fixes what a program may depend on — the
+  instance, the shapes of a recipe, a playbook, a finding and a run event, the permitted actions,
+  the three interfaces — and [docs/downstream.md](docs/downstream.md) is now the same three in
+  use: an example of each and a pointer to the rule, instead of a second wording of it. The page
+  ships with the package alongside `CONTRACT.md`, and `test/downstream-doc.test.ts` reads both:
+  every name §2.2 fixes exists in the source, and the page's JSON example is `FINDING_FIELDS`
+  exactly.
+- **A run's two hook events are built once.** `run_start` and `run_end` were assembled twice,
+  near-verbatim, in the interactive extension and in the headless host — so which process held the
+  clock could change what a rule saw, and nothing but a comment said it should not. Both now call
+  `runStartEvent` / `runEndEvent` in `src/hooks.ts`, and the `run_*` fields
+  [docs/downstream.md](docs/downstream.md) §2 names are pinned by a test there.
+
+### Fixed
+- **A number is refused where no list was printed, by the resolver itself.** `pi-loops inbox claim 1`
+  was refused by one line in the CLI while the resolver underneath still resolved `1` to the first
+  finding, and the model-facing tools guarded jobs and rules the same way, each on its own.
+  `resolveInboxRef`, `resolveJobRef` and `resolveRuleRef` now resolve an all-digit reference to
+  nothing unless the caller says `ordinals: true`, which only `/inbox`, `/cron` and `/triggers`
+  do — they number what they show. The CLI and the tools no longer carry their own check, and the
+  messages a person sees are unchanged.
+- **daily-digest reads nothing under the loops directory.** Its playbook told a run to read
+  `runs.jsonl` and `jobs.json`, two files [docs/downstream.md](docs/downstream.md) says change
+  without notice; it now asks the `cron_list` tool, which lists each job's `last_error` and, new,
+  its `consecutive_failures`, and `pi-loops inbox list --json` for the findings still waiting. The
+  contract check that installs every packaged recipe and searches its files for the names of the
+  private files (`test/contract/1-second-implementation.sh`) is what caught it, and what keeps the
+  next recipe from doing the same.
+- **One archive, one set of answers.** `/session-export` and `pi-loops export`, and
+  `/session-import` and `pi-loops import`, decided the same three things twice and had drifted
+  apart on all three; each decision now lives once, in `src/archive.ts`. What changes:
+  `pi-loops export` follows the session that created a job or rule, the way the slash command
+  always has, instead of archiving every loop in the project — including a colleague's, and
+  including none of your own reached through a worktree or a symlinked path, which its
+  string comparison of directories missed. `/session-import` takes `--activate-triggers=ask` and
+  the space-separated `--activate-triggers ask`, both of which it used to refuse. `pi-loops import`
+  defaults to `ask` like the slash command (it defaulted to `off`), asks after the import rather
+  than before it, with the counts, and rolls a half-written import back — a failed store write
+  used to leave the jobs in, the loop state on disk, and a session file nothing pointed at.
+
+## [0.21.0] - 2026-09-16
+
+### Added
+- **What a program may depend on.** [docs/downstream.md](docs/downstream.md) is the whole list of
+  what a program that is not pi-loops may rely on: a recipe directory, `run_start` / `run_end` in
+  `hooks.toml` with their `PI_RUN_*` variables, and `pi-loops inbox list | claim <id> | dismiss <id>
+  [--reason <text>] --json` — a new command that does what `/inbox` does with no pi open — and it
+  says that nothing else is one: no file under `~/.pi/agent/loops`, no slash command's wording,
+  not the browser page. The list is small on purpose: every name on it is a promise never to
+  rename or remove, so it holds only what a closed loop needs. That the list is *enough* is
+  proved rather than asserted: `test/downstream/fixture-recipe/` is a recipe that uses only it —
+  installed from its directory, its run commits a file and files a checkpoint, and its `run_end`
+  hook finds that finding by `PI_RUN_ID` and claims it — and `test/downstream/closed-loop.sh`
+  checks the file, the commit and the claim from the outside with `sh` and `jq`, importing none
+  of this package's code; the model is a loopback stand-in (`npm run check:downstream`, part of
+  `npm run ci`). The third item was added for that proof: with only the first two, a hook could
+  count a run's findings but neither read nor mark one. A test keeps the page honest the other
+  way: every `PI_RUN_*` variable, manifest key and finding field it names must exist in `src/`.
+- **A dismiss can say why, and the loop hears it.** `/inbox dismiss <n> <reason>` keeps the
+  reason on the entry (`dismiss_reason`, with `dismissed_at`) and puts it in front of the next run
+  of the loop that reported the finding, in a `[dismissed]` block between its notes and its task:
+  do not report this again unless what it describes has changed, and carry into your notes what
+  you need to remember that. Shown to that one run only — the notes are the loop's only memory,
+  and a channel the notes cap does not bound would be one it could not edit. Up to eight per run,
+  newest kept. A bare dismiss and `/inbox clear` stay silent as before; `/inbox all` shows the
+  reason on the dismissed line. Until now the only answer to a finding was to claim it or to say
+  nothing, and a loop that misjudged what counts as a finding went on misjudging it every night.
+- **`deps-sweeper` recipe.** Mondays at eight: the project's audit and outdated commands, and one
+  finding per advisory or major-version gap not already in its notes. Under `propose`, patch and
+  minor updates are applied in a worktree, the project's check command run, and a pull request
+  opened — one per run, never a major, never a package on the playbook's deny list, and the same
+  package attempted twice without a green check is a stop. Eight recipes now ship.
+- **Was it worth running.** `/cron` shows, per loop, the last thirty days of findings filed and
+  what a person did with them (`30d: 6 findings · 6 dismissed (4 with a reason)`), and marks
+  `[quiet ×N]` once the N newest runs found nothing. `/cron cost` puts the same counts beside each
+  job's spend. `cron_list` gives the model both (`signal_30d`, `quiet_streak`). Computed from the
+  run log and the inbox (`src/job-signal.ts`); nothing is stored and no schedule is changed — a
+  quiet watch is supposed to be quiet, and the number is what to read before making it hourly.
+- **Every checkpoint says three things.** A finding that asks a person to decide now carries, in
+  every packaged playbook, the decision, what waits on it, and what happens if nobody acts
+  (`… · waits: your merge · if not: the branch stays; later runs build on it`). docs/recipes.md
+  has the shape. News — a merged pull request, a red check — stays as it was.
+- **autoresearch looks back.** Five retired experiments in a row since the last kept one is a
+  finding asking whether the contract is wrong, and the loop stays out of the idea classes it has
+  exhausted; ten in a row stops it until `RESEARCH.md` changes. Before this an hourly loop in the
+  wrong search space ran until the budget cap.
+- **What a recipe may never do, before it is installed.** `/recipe show` and the install
+  confirmation print each playbook's `## Never` section — the safety envelope of an unattended
+  run, which until now was read after the install, if at all — with a `tier` line and the
+  situations the recipe is for (`useful_when` in the manifest). `/recipe list` shows the eight in
+  two groups: three starters that only read and file findings (`daily-digest`, `pr-watch`,
+  `changelog-draft`), and the advanced ones that write to a worktree, a tracker or a pull request.
+  The four playbooks that kept their prohibitions in the body (`triage`, `implement`, `release`,
+  `experiment`) gain the section, with nothing new in it; `/recipe update` carries it into
+  installed copies.
+- **A recipe is checked against the project before it is installed.** The confirmation ends
+  with *Before the first run*: whether `gh` is there and logged in, whether there is an `origin`,
+  a CI workflow, a lockfile, whether the tracker is GitHub — each a line with ✓ or ✗ and what the
+  miss means for the runs. Nothing blocks the install. A manifest names its checks (`needs`,
+  `needs_propose`); a recipe that reads the tracker is checked for `gh` only when the tracker
+  description uses it, so a local Markdown tracker is asked for nothing. `/recipe show` prints
+  the same lines. Until now the first sign of a missing login was an empty inbox the next morning.
+- **The inbox tells a decision from news.** A finding in the checkpoint shape
+  (` · waits: … · if not: …`) is stored with `kind: "checkpoint"` when the run's findings are
+  appended. `/inbox` lists checkpoints first, marks them `⚑`, and says `3 new, 1 needs a decision`
+  in its header; the footer badge and the browser panel say `(1 decision)`. Claiming one tells the
+  turn that the claim is the person's approval of the decision the finding recommends, so it is
+  carried out rather than investigated again. Entries written before this read as news.
+- **Esc pauses the goal.** Stopping a turn with Esc while a `/goal` is pursued pauses the goal —
+  appended to the session, so `--resume` finds it paused — until `/goal resume`. Until now the
+  aborted turn was merely not judged, and the next message ended with the evaluator sending the
+  agent back to work. Esc during an evaluation stopped it before and still does.
+
+### Fixed
+- **issue-loop installs on a local Markdown tracker.** Its setup script ran `gh label create`
+  whatever the tracker was, so a project with `.scratch/issues/` and no `gh` stopped at "setup
+  script failed; no jobs were created". The script now reads `docs/agents/issue-tracker.md`: a
+  local tracker has no labels to create and it says so; a GitHub tracker without `gh`, or with
+  `gh` not logged in, is told what to run by hand and the install goes on — the first run reports
+  what it cannot do. The local tracker description gains the two operations it never named:
+  requesting changes (a comment and the status back to `agent-working`) and merging (`git merge`,
+  status `done`, file to `closed/`), and the implement playbook reads review feedback from the
+  item's comments where there is no pull request.
+
 ## [0.20.0] - 2026-09-14
 
 ### Added

package/CONTRACT.md

@@ -0,0 +1,139 @@
+# pi-loops — CONTRACT
+
+Version 0.22 · 2026-09-16 · Status: draft · Section 2 frozen at 29 lines
+
+This file does one thing. It says which things never change (the contract), which things can be
+replaced at any time (the mechanisms), and how to prove that a mechanism has not quietly become
+part of the contract (the refinement checks). Section 2 says what the project is. Every other
+section can be deleted or rewritten without changing the project.
+
+## 0. One sentence
+
+The loops directory on one machine holds jobs, findings and each loop's notes. pi-loops runs the
+jobs on a clock, queues the findings, and emits an event before and after each run. A program
+talks to it only through a recipe directory, `hooks.toml`, and the `pi-loops inbox` command.
+
+## 1. Terms
+
+- **Loops directory**: the directory pi-loops reads and writes on one machine (default
+  `~/.pi/agent/loops`, overridden by `PI_LOOPS_DIR`).
+- **Project**: the directory a job runs in (`cwd`).
+- **Job**: one schedule and one prompt, belonging to one project.
+- **Run**: one execution of a job, with one `run_id`.
+- **Finding**: one line a run leaves for a person, with a status `new`, `claimed` or `dismissed`.
+- **Notes**: the Markdown a loop's run leaves for its next run.
+- **Recipe**: a directory: `recipe.toml` and the playbooks it names.
+- **Playbook**: the Markdown a run reads, copied into the project at install.
+- **Level**: the line `Autonomy: report | propose | act` in a playbook.
+- **Event**: the payload a `hooks.toml` rule sees when a run starts and when it ends.
+
+## 2. Contract (MUST)
+
+### 2.1 Instance
+
+- Instance data in the loops directory: the jobs, the trigger rules, the findings, the notes, the run records (including each run's transcript), `hooks.toml`, `config.toml`, `mcp.toml`. Every other file and directory there is private state and can be deleted at any time.
+- Instance data in a project: the playbooks and recipe files installed under `.agents/skills/<recipe>/`, and, when a recipe declares `needs_tracker`, `docs/agents/issue-tracker.md`.
+- Tool code does not enter an instance. Instance data does not enter the tool.
+
+### 2.2 Unit formats
+
+- **Recipe**: `recipe.toml` is TOML. Required: `name` (a lowercase letter, then lowercase letters, digits and hyphens), `summary`, `levels` (non-empty, from the three levels), at least one `[[job]]`. Each `[[job]]` requires `name`, `schedule` (a recurring schedule) and `playbook` (a file in the same directory). Optional keys: `needs_tracker`, `setup`, `files`, `tier`, `useful_when`, `needs`, `needs_propose`, `budget_hint_usd`; per job `verify`, `timeout`, `thinking`, `tools`, `prompt`.
+- **Playbook**: Markdown with pi's skill frontmatter (`name`, `description`), one level line, and one `## Never` section.
+- **Finding**: one JSON object with the fields `id`, `created_at` (RFC 3339), `status`, `kind` (`checkpoint` | `news`), `source`, `run_id`, `cwd`, `text`, `verified` (`true` | `false` | `null`), `dismiss_reason` (string | `null`). Fields are only added at the end; none is renamed, removed or changed in type.
+- **Event**: `run_start` and `run_end`. The payload has `run_job` and `run_id`; on `run_end` also `run_ok`, `run_findings`, `run_error`, `run_cost_usd`. Each field also enters the command's environment as `PI_<FIELD IN UPPER CASE>`, unset when the payload has `null`.
+- **Rule**: a `[[hook]]` in `hooks.toml` with `event` and either `command` or `webhook`.
+
+### 2.3 Permitted actions
+
+- **Install a recipe**: copy the playbooks into the project with the level line written, and create the jobs the manifest declares. A manifest that breaks a rule is refused whole; no file is copied.
+- **Run**: emit one `run_start` and one `run_end` with the same `run_id`. The run's findings enter the queue with `status = new` and `run_id` = that run.
+- **Claim** and **dismiss**: take a finding's `id` or a unique prefix of it, and succeed once each, only on a `new` finding. Dismiss can carry a `reason`, written to `dismiss_reason`.
+
+### 2.4 Ledger
+
+The events are the ledger of runs: each run has exactly one `run_start` / `run_end` pair. A finding's `status` is its own ledger: `new → claimed` or `new → dismissed`, never back.
+
+### 2.5 Write conditions
+
+A finding is written only by a run, and its `text` is what the run said. `status` changes only through claim or dismiss. A rule that fails or hangs does not change the run's result. An install is complete or does not happen.
+
+### 2.6 Deterministic rules
+
+- `kind`: `text` contains `· waits:` (preceded by the start of the text or whitespace, case-insensitive) → `checkpoint`; otherwise `news`.
+- Level line: the first line that is exactly `Autonomy: <one word>`. When that word is one of the three levels, it is the level; otherwise the playbook has no level.
+- Manifest validity: the required keys and values of 2.2. TOML is parsed as standard TOML.
+
+### 2.7 Downstream interface
+
+1. A recipe is a directory. `/recipe add <dir>` and `pi-loops recipe add <dir>` install it.
+2. A `hooks.toml` rule with `event = "run_start" | "run_end"` receives the event of 2.2.
+3. `pi-loops inbox list [--all] [--cwd <dir>] --json`, `inbox claim <id> --json`, `inbox dismiss <id> [--reason <text>] --json`: exit 0 and one JSON object (`{"findings": [...]}` or `{"finding": {...}}`); on failure exit 1 and `{"error": "<why>"}`.
+
+Any file, field, path or command not listed above is not an interface.
+
+### 2.8 Boundary
+
+That is all. This section fits on one screen.
+
+## 3. Mechanisms (SHOULD, replaceable)
+
+Three sentences each: what it is, what it depends on, and why the contract does not move when it is replaced.
+
+- **Findings are stored in `inbox.jsonl`, one object of 2.2 per line.** Depends on line-atomic appends. Another container keeps the object; `inbox` returns it as before.
+- **An id is `inb-` and 32 hex characters; a run_id is `run-` and the same.** Depends on `randomBytes(16)`. The contract asks only that ids be unique and resolvable by prefix.
+- **`created_at` carries the local UTC offset.** Depends on `stamp()` in `schedule.ts`. The contract asks only for RFC 3339.
+- **`source` is `cron:<job name or id>`.** Depends on the scheduler. The contract asks only for a string.
+- **`inbox list` puts checkpoints first, then news, each oldest first.** Depends on the sort in `inbox.ts`. The contract asks only for the right set.
+- **A finding's `text` is at most 500 characters, a run files at most 16, notes are at most 2000 characters, a prompt at most 8 KB.** Depends on the model's context and the queue staying readable. Changing a number does not touch 2.2.
+- **`inbox.jsonl` drops its oldest handled entries past 1 MB.** Depends on disk and list length. The contract only requires that `new` findings can be listed.
+- **Jobs live in `jobs.json` (`version: 2`), notes in `state/<id>.md`, run records in `runs.jsonl`.** Depends on the current store. A job's full description is its `/cron add` line; reinstalling the recipe recreates it.
+- **An install leaves an `.orig/` copy and `.recipe.json` in the project and lists the directory in `.git/info/exclude`.** Depends on the three-way merge of `/recipe update` and on keeping playbooks out of the repository's history. Another merge strategy leaves 2.1 and 2.3 as they are.
+- **The values of `needs` and `needs_propose` are the preflight checks this version performs (`gh`, `git-remote`, `ci-workflows`, `lockfile`, `tracker-github`).** Depends on this version's set of checks. A recipe that names a check this version does not have is refused; that binds the recipe to a version and does not change the contract.
+- **A recipe name is at most 64 characters.** Depends on the install directory name staying readable.
+- **A rule's command times out after 5000 ms, its stdout is cut at 4000 characters, summaries at 2000, and the host drains for 3 seconds before it exits; output goes to `logs/pi-<pid>.log` or `host.log`.** Depends on log rotation. Changing any of these numbers leaves the event fields of 2.2 as they are.
+- **Creating a job needs a pi (interactive, or `pi --mode rpc`).** `pi-loops recipe add` in a terminal only copies files and prints the `/cron add` lines. Depends on the decision that a job belongs to a session. The "create the jobs" of 2.3 is done by `/recipe add` inside pi.
+- **A headless host runs the jobs while no pi is open.** Depends on the process hand-off. Events and findings have the same shape in both processes.
+
+## 4. Not done
+
+- No public format for `jobs.json`: a job is created by a recipe install or by a person in pi, and a reinstall recreates it (2.3 + mechanism "jobs live in `jobs.json`").
+- No second on-disk shape for a finding (such as another tool's field names): a line is the object of 2.2, and another tool reads it as it is (2.2 + mechanism "`inbox.jsonl`").
+- Playbooks do not read files in the loops directory: a run learns its own health from the `cron_list` tool and the findings from `pi-loops inbox` (2.7).
+- `mcp.toml` is not a program interface: it is a person's configuration file (instance data in 2.1, not in 2.7).
+- No command that creates a job from a terminal: `pi --mode rpc` already runs `/recipe add` without a terminal (mechanism "creating a job needs a pi").
+- No multi-machine support: one loops directory belongs to one machine (design.md, decision 19).
+
+## 5. Refinement checks
+
+The scripts are in `test/contract/`. `sh test/contract/run.sh` runs all five; each also runs alone.
+
+1. **Second implementation** `test/contract/1-second-implementation.sh`: `test/downstream/closed-loop.sh` (sh and jq install a recipe, let it run, find its finding by `run_id` and claim it, touching no private file), then python3 `tomllib` reads every packaged `recipe.toml` and checks the required keys of 2.2; then every packaged recipe is installed with `pi-loops recipe add` and its files are searched for the names of the loops directory's files. Pass: every step exits 0 and no playbook names a private file. A failure means private state has leaked into the contract, or a recipe depends on it.
+2. **Stopped machine** `test/contract/2-stopped.sh`: with no pi and no host running, write a `hooks.toml` rule, install a directory with `pi-loops recipe add`, and dismiss a finding with `pi-loops inbox dismiss`. Pass: all three succeed. A failure means a write depends on a mechanism.
+3. **Cross-check** `test/contract/3-cross-check.sh`: four rules, each run through two implementations that share nothing, over the same samples; pass when the outputs are equal line for line. TOML: `src/toml.ts` against python3 `tomllib`, over every `recipe.toml` in the repository and `examples/mcp.toml`. `kind`: `src/protocol.ts` against `grep -E`, over every `<inbox>` text the repository has shown. Level line: `src/recipe.ts` against `awk`, over every playbook in `recipes/` and in this repository's `.agents/skills/`. Finding: `pi-loops inbox list --all --json` against `jq` reading the ten fields of 2.2 off each line of `inbox.jsonl` directly. Event: the same loop run once by the host and once by a pi driven over rpc; the two `run_end` payloads have the same fields and the same run values.
+4. **Private state cleared** `test/contract/4-private-state.sh`: after one run, delete everything in the loops directory that 2.1 does not name as instance data and start the host again. Pass: it runs the loop again and the earlier findings are unchanged field for field.
+5. **Contract size** `test/contract/5-size.sh`: section 2 has no more non-empty lines than the count frozen in this file's header. Pass when it does not. A line added there must name, in the CHANGELOG, the mechanism it replaced.
+
+## 6. Mapping of requirements and features
+
+| Requirement or feature | Where it lands |
+|---|---|
+| `docs/downstream.md` | examples of 2.2 / 2.3 / 2.7; the rule is here |
+| `docs/downstream.md` §1, the recipe directory | Contract 2.2 / 2.7.1 |
+| `docs/downstream.md` §2, the hook events | Contract 2.2 / 2.7.2 |
+| `docs/downstream.md` §3, the inbox command and the finding object | Contract 2.2 / 2.3 / 2.7.3 |
+| `inb-<32 hex>`, 500 characters and the list order in `docs/downstream.md` | Mechanism |
+| `docs/recipes.md`, "Writing a recipe" | Contract 2.2; `.orig/`, `.recipe.json`, exclude, preflight names → mechanism |
+| Timeouts, truncation and log paths in `docs/hooks.md` | Mechanism |
+| The on-disk line shape (`trace_id`) that `docs/loops.md` used to document | Removed, unreleased: a line is the object of 2.2 (CHANGELOG, "One shape for a finding") |
+| The four caps in `docs/design.md`, decision 11 | Mechanism |
+| `docs/design.md`, decisions 15–18 (recipes are files, copied into the project, deterministic wizard, the level is a sentence) | Contract 2.1 / 2.2 / 2.3; details → mechanism |
+| `recipes/daily-digest` reads `runs.jsonl` and `jobs.json` | Not done, item 3 |
+| `examples/mcp.toml` | Not done, item 4 |
+| `test/downstream/` | Part of refinement check 1 |
+
+## 7. Revision rules
+
+- The required fields and the actions of section 2 are only added, never changed or removed.
+- No number derived from a mechanism appears in the contract.
+- A mechanism paragraph can be replaced whole; replacing one only requires rerunning section 5.
+- This file is part of the repository; a change to it goes through the ledger.

package/README.md

@@ -38,7 +38,7 @@ the first sign of credentials that do not work should not be an empty inbox tomo
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # from npm, following new releases
-pi install git:github.com/alphacoder-v0/pi-loops@v0.20.0    # or from GitHub, at a pinned tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.22.1    # or from GitHub, at a pinned tag
 pi install /path/to/pi-loops                                # or a local checkout — `pi install .` in this repo
 pi -e /path/to/pi-loops                                     # or none of them: try it for one run, installing nothing
 ```
@@ -103,6 +103,7 @@ watching this repo lands in the same list and you triage it in one pass.
 /cron run 1            # do not wait until 9am — run it now and watch
 /inbox claim 1         # hand finding #1 to the agent as a real turn
 /inbox dismiss 2       # not interesting
+/inbox dismiss 3 that file is generated, ignore it    # the loop is told why on its next run
 ```
 
 ## Loops worth stealing
@@ -138,11 +139,13 @@ A job records its directory and model at creation, so it is not tied to the wind
 `--cwd` runs it in another checkout (absolute, or relative to this project — no shell, so nothing
 expands `~`), and `--model` pins it whatever this session is on (`/cron set <ref> --model -` unpins).
 
-And seven you do not write at all: `/recipe add issue-loop` runs the issue tracker as a state
+And eight you do not write at all: `/recipe add issue-loop` runs the issue tracker as a state
 machine that two loops turn, `/recipe add autoresearch` runs one experiment per run against a
-contract you wrote, and `daily-digest`, `pr-watch`, `ci-sweeper`, `changelog-draft` and
-`ecosystem` do what their names say — each a directory of playbooks copied into the project,
-installed with one question and one confirmation ([docs/recipes.md](docs/recipes.md)).
+contract you wrote, and `daily-digest`, `pr-watch`, `ci-sweeper`, `deps-sweeper`,
+`changelog-draft` and `ecosystem` do what their names say — each a directory of playbooks copied
+into the project, installed with one question and one confirmation, and `/recipe show` says
+what its runs may never do before you say yes ([docs/recipes.md](docs/recipes.md)). Three are
+starters that only read and file findings: `daily-digest`, `pr-watch`, `changelog-draft`.
 
 Two that are not loops:
 
@@ -285,7 +288,7 @@ State stays in `~/.pi/agent/loops` until you delete it.
 | `/cron gc` | Remove plain jobs whose session was deleted (they are parked as disabled first) |
 | `/cron panel on\|off` | The side panel above the editor: Triggers, Inbox, Cron, MCP |
 | `/cron snapshot` | Write what only this process knows — connected MCP servers and their tools, active tools, hooks, who owns the clock — into the session as a `pi_loops_snapshot` entry, for a front end that is not a terminal |
-| `/inbox [list\|all\|claim <n>\|dismiss <n>\|clear] [--all]` | Triage findings from stateful loops. This project's by default, `--all` for every project — the same scoping `/cron` and `/triggers` use |
+| `/inbox [list\|all\|claim <n>\|dismiss <n> [reason]\|clear] [--all]` | Triage findings from stateful loops. This project's by default, `--all` for every project — the same scoping `/cron` and `/triggers` use. A reason given with `dismiss` is shown to the loop's next run |
 | `/goal [<condition>]`, `/goal pause\|resume\|clear` | Hold the session to a stop condition: after every turn an evaluator with no tools decides whether it is met, and sends the agent back to work if not (max 8 continuations). Bare `/goal` shows the one in force |
 | `/new-trigger <natural language>` | Create a condition-based rule ("when ~/build.done exists, run cargo test") |
 | `/triggers [status\|rules\|enable\|disable\|remove\|running\|audit [N]\|abort]` | Dynamic rules: what exists, what is running, what happened |
@@ -326,7 +329,8 @@ notifications, and lifecycle hooks — each has a page here.
 - [docs/goal.md](docs/goal.md) — `/goal`: holding a session to a stop condition
 - [docs/recipes.md](docs/recipes.md) — `/recipe`: a project run on loops, installed in one command; the issue loop and autoresearch, and how to write your own
 - [docs/session-archive.md](docs/session-archive.md) — `/session-export`, `/session-import`
-- [docs/cli.md](docs/cli.md) — the `pi-loops` command line: export, import, and looking in on the host
+- [docs/cli.md](docs/cli.md) — the `pi-loops` command line: export, import, the inbox, and looking in on the host
+- [docs/downstream.md](docs/downstream.md) — what a program may depend on: a recipe directory, `run_start` / `run_end`, `pi-loops inbox --json`; nothing else
 - [docs/web-ui-parity.md](docs/web-ui-parity.md) — what the browser front end owes you, line by line
 - [docs/configuration.md](docs/configuration.md) — paths, `config.toml`, flags, environment
 - [docs/design.md](docs/design.md) — architecture: what each piece is built out of, and the decisions behind it

package/README.zh-CN.md

@@ -45,7 +45,7 @@ pi-loops 自己没有任何运行时依赖。
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # 从 npm 装，跟着新版本走
-pi install git:github.com/alphacoder-v0/pi-loops@v0.20.0    # 或者从 GitHub 装，钉住一个 tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.22.1    # 或者从 GitHub 装，钉住一个 tag
 pi install /path/to/pi-loops                                # 或者本地检出；本仓库里就是 pi install .
 ```
 
@@ -130,6 +130,7 @@ claim with /inbox claim <n>, dismiss with /inbox dismiss <n>
 /cron run 1                                        # 不用等到早上九点，现在就跑一次看看
 /inbox claim 1                                     # 把第 1 条作为真实的一轮交给 agent
 /inbox dismiss 2                                   # 不感兴趣
+/inbox dismiss 3 那个文件是生成的，别管它             # 理由会放进这个 loop 下一次 run 的 prompt 里
 ```
 
 ### 5. 让它整夜跑之前
@@ -221,6 +222,7 @@ pi update --extensions                             # 对齐已安装的包
 /recipe                    有哪些打包好的 recipe，这个项目装了哪些
 /recipe add issue-loop     把 issue tracker 跑成状态机：分诊成 agent brief、在 worktree 里实现、开 PR；推进和合并留给人
 /recipe add autoresearch   按你写的研究合同每次跑一个实验，账本记下每次尝试，只凭 held-out 数据提议晋升
+/recipe add deps-sweeper   每周一跑 audit 和 outdated：新的安全通告和落后一个大版本的依赖各报一条；propose 级在 worktree 里做小版本升级并开 PR
 ```
 
 一个 recipe 是一组 loop 加上它们各自每次 run 都会读的 playbook。安装只问一个问题（自治级别
@@ -263,7 +265,7 @@ playbook 拷到 `.agents/skills/<name>/`，通过 `.git/info/exclude` 排除在
 
 /inbox                              本项目的新 findings（每行标出项目；`--all` 看全部项目，与 /cron、/triggers 同一套作用域）
 /inbox claim 1                      标记 claimed，并把它作为一个真实 user turn 交给主会话的 agent
-/inbox dismiss 2  ·  /inbox clear  ·  /inbox all
+/inbox dismiss 2 [理由]  ·  /inbox clear  ·  /inbox all     写了理由，报这条的 loop 下次 run 会看到；不写则沉默
 ```
 
 `/crontab` 和 `/loop` 是 `/cron` 的别名。
@@ -341,7 +343,7 @@ pi 内置的 `/export` 只导 HTML/JSONL 对话，`/import` 只导回对话—
 
 ```text
 /session-export [path] [--exclude-triggers]          默认 ./pi-session-<id前16位>.pisession
-/session-import <path> [--activate-triggers=on|off] [--cwd <dir>] [--resume]
+/session-import <path> [--activate-triggers=off|ask|on] [--cwd <dir>] [--resume]
 ```
 
 ```text
@@ -356,7 +358,7 @@ backup.pisession                 无压缩 ustar，0600，拒绝覆盖已有文
 导入的时候会重写这些：
 
 - session 换新 id，cwd 改成目标目录，header 里记下 `importedFrom` 来源。
-- 任务和规则默认全部 disabled。`--activate-triggers=on` 会弹一次确认，问你要不要把源会话里原本 enabled 的那些重新打开。
+- 任务和规则默认全部 disabled。`--activate-triggers` 默认 `ask`：导入完之后弹一次确认，问你要不要把源会话里原本 enabled 的那些重新打开；`off` 不问，`on` 直接打开。
 - 运行标记、错误、重叠计数清零。
 - id 撞上本机已有的就重新生成，loop 状态文件跟着新 id 走。
 - 非 stateful 任务重新绑定到导入的 session。

package/docs/cli.md

@@ -169,8 +169,13 @@ node src/cli-entry.mjs install-launcher
 node src/cli-entry.mjs install-launcher --dir ~/bin
 ```
 
-It writes a two-line `sh` script that names the node you ran it with and the package it lives in —
-a launcher rather than a symlink, so it keeps working if either moves for the other's reason.
+It writes a small `sh` script that names the node you ran it with and the package it lives in — a
+launcher rather than a symlink. Neither path is trusted for ever: if the package is not where it
+was, the launcher looks in both of the directories above (the ones pi installs into, under the agent
+directory this was written with), so installing again by the other route does not break it, and if
+that node has gone it falls back to the `node` on your `PATH`. When no copy is in any of them it
+prints one line saying to run `install-launcher` again — from inside pi, or from wherever pi has put
+the package now — instead of a Node stack trace about a missing file.
 
 ## Upgrading
 
@@ -209,6 +214,8 @@ pi-loops inspect <file>
 pi-loops export [--session <id>] [--cwd <dir>] [--output <file>] [--exclude-triggers]
 pi-loops import <file> [--cwd <dir>] [--activate-triggers=off|ask|on]
 pi-loops host status | abort <run-id|trace-id> | stop
+pi-loops recipe list | show <name|path> | add <name|path> [--cwd <dir>] [--level report|propose|act] [--overwrite]
+pi-loops inbox list [--all] [--cwd <dir>] | claim <id> | dismiss <id> [--reason <text>]   [--json]
 ```
 
 ## sessions, inspect
@@ -239,7 +246,10 @@ pi-loops export --session 01a084a0 --output ~/backups/api.pisession
 Restores an archive into `--cwd` (default: the current directory), rewriting ids, project and
 machine so the automation runs where it landed.
 
-Imported automation stays disabled unless `--activate-triggers=on`; `ask` prompts on a terminal.
+`--activate-triggers=off|ask|on` decides what happens to the automation the archive carries, and
+means the same thing here as in `/session-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.
 Importing the same archive twice adds nothing the second time.
 
 ## host
@@ -280,3 +290,16 @@ record — and stops. The setup script and the jobs need a pi open in the projec
 them after you say yes. Without `--level` the lowest level the recipe supports is written; an edited
 copy is kept unless `--overwrite` says otherwise.
 
+## inbox
+
+```sh
+pi-loops inbox list --json                    # this project's new findings, checkpoints first
+pi-loops inbox claim inb-3f2a… --json         # mark it claimed; acting on it is yours
+pi-loops inbox dismiss inb-3f2a… --reason "that file is generated" --json
+```
+
+`/inbox` with no pi open ([loops.md](loops.md#the-inbox)). `claim` and `dismiss` take an id or a
+unique prefix of one and change the entry the way the slash command does; a claim here cannot start
+a turn, so it marks the finding and leaves the acting to whoever asked. Without `--json` the same,
+one line per finding, for a person. The JSON is fixed in [CONTRACT.md](../CONTRACT.md) §2.2 and shown in [downstream.md](downstream.md), which is
+the page a program should be written against.

package/docs/downstream.md

@@ -0,0 +1,60 @@
+# What a program may depend on
+
+Three things, and this page is the whole list. A program that is not pi-loops and does not import
+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
+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.
+
+The three are named in [CONTRACT.md](../CONTRACT.md) §2.7 and their shapes in §2.2 — that is where
+the rule lives, and the text that moves when one of them changes. This page is the three in use.
+
+## 1. A recipe is a directory
+
+`recipe.toml` and the Markdown playbooks it names, side by side; `/recipe add ./dir` and
+`pi-loops recipe add ./dir` install it from a local path. What the manifest may say — every key it
+requires and every one it allows — is [CONTRACT.md](../CONTRACT.md) §2.2; what a playbook is, and
+how one is written, is one section of [recipes.md](recipes.md#writing-a-recipe). A manifest that
+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
+[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
+`PI_HOOK_PAYLOAD`; [hooks.md](hooks.md) shows a rule. A hook that fails or hangs never fails the run.
+
+## 3. `pi-loops inbox list | claim <id> | dismiss <id> --json`
+
+No pi needs to be open. Exit 0 and one JSON object on stdout; on failure exit 1 and `{"error": "<why>"}`.
+
+```
+pi-loops inbox list [--all] [--cwd <dir>] --json      {"findings": [<finding>, …]}
+pi-loops inbox claim <id> --json                       {"finding": <finding>}   now "claimed"
+pi-loops inbox dismiss <id> [--reason <text>] --json   {"finding": <finding>}   now "dismissed"
+```
+
+`list` is what `/inbox` shows: the new findings of the project at `--cwd` (default: the current
+directory), checkpoints first, then news, each oldest first; `--all` is every project. `claim` and
+`dismiss` take a finding's `id` or a unique prefix of it (never a number), among the new findings
+machine-wide, and do to the entry what `/inbox claim` and `/inbox dismiss` do — the two actions of
+[CONTRACT.md](../CONTRACT.md) §2.3: `claim` marks it and stops, since there is no session to hand
+it to; a `--reason` is shown to the loop's next run. The object they print is the one of §2.2,
+field for field:
+
+```json
+{"id": "inb-<32 hex>", "created_at": "2026-09-16T09:00:00.000+08:00", "status": "new",
+ "kind": "checkpoint", "source": "cron:nightly-audit", "run_id": "run-<32 hex>",
+ "cwd": "/path/to/project", "text": "one line, at most 500 characters", "verified": null, "dismiss_reason": null}
+```
+
+Fields may be added; none of these will be renamed, removed or change type.
+
+Not listed here means private. `test/downstream/` is the proof this list is enough: a recipe that
+uses only it, checked from the outside with `sh` and `jq`. `test/contract/` holds the checks of
+CONTRACT.md itself.

package/docs/goal.md

@@ -31,10 +31,12 @@ is told to answer `{"ok": false, "reason": "insufficient evidence in transcript"
 | Evaluator failure | Pauses with the reason; it never loops on an evaluator that cannot decide |
 | Transcript | 40 000 characters, truncated from the front so the newest evidence always survives |
 | Tools | None. The evaluator reads, it does not act |
-| Interruption | A turn you aborted is not judged, and Esc during an evaluation stops it |
+| 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. `pause`, `resume` and `clear` are
+`/goal resume` after a budget limit starts the allowance again, 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
 matched as whole words, so `/goal clear the type errors first` sets that as the condition rather
 than dropping the goal.