@alphacoder-v0/pi-loops 0.17.6 → 0.19.2

package/CHANGELOG.md

@@ -3,6 +3,97 @@
 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.
 
+## [0.19.2] - 2026-09-14
+
+### Fixed
+- **A plain job of another session was promised a next run, could be run into the wrong chat, and
+  was called dormant as if that were a fault** (#15). A plain job belongs to the session that
+  created it — its result is a message in that conversation — and dispatch has always honoured
+  that; the lists did not. `cron_list` printed a `next_run` for a job this process would never
+  dispatch (the same class the `[other host]` fix closed for the machine half of the predicate),
+  the browser panel showed the time it read from `next-runs.json`, and `/cron run` injected the job
+  into whatever chat was open. On 2026-09-14 a daily digest missed its slot exactly this way, and
+  the only surface that knew was the terminal's `[dormant …]` marker. Now one predicate
+  (`src/job-owner.ts`) answers "does it run here" for dispatch, `/cron`, `cron_list`, the panel and
+  `/cron run`: another session lists it as `[session <id> — resume it to run]` with no next run,
+  `cron_list` says the same and sets `owner_session` / `asleep`, the panel says what would wake it,
+  and `/cron run` refuses it with the same sentence. "Asleep" replaces "dormant" in the vocabulary:
+  it is waiting for its conversation, not broken. The `catch_up` description now says when a
+  plain job's missed slot is honoured (when its session is next opened); the skill tells the model
+  that anything meant to run unattended is a loop. Parking stays what it was and is now documented
+  as such: a plain job is disabled once its session's file has been deleted, not before.
+
+## [0.19.1] - 2026-09-14
+
+### Changed
+- **`pi-loops sessions` says what a session is, not only which.** It printed the id, the mtime and
+  the cwd, so telling two sessions apart meant opening them. It now prints one line a person can
+  tell them apart by: the short id, when the session started, the automation it has
+  (`[2 cron, 1 trigger]`, `[automation off]`), and what was first said in it — the name it was
+  given, or the first message cut at eighty characters, by characters and never inside one.
+  `--all` puts the cwd after the id. `src/session-head.ts` reads the head of a session file for
+  it; the browser front end's own copy of that reading is unchanged.
+- **The session commands are two words in the browser front end.** `/sessions` lists this
+  project's sessions in the feed, and `/session export [path]` / `/session import <path>` are the
+  archive commands, delivered as `/session-export` / `/session-import`. pi's built-in `/session` is
+  a terminal command that does not exist over rpc — that is why the extension's commands are
+  hyphenated in the terminal, and why the page can spell them plainly.
+
+## [0.19.0] - 2026-09-14
+
+### Removed
+- **The machine, as a concept.** Every job and rule used to carry the hostname that created it;
+  another machine sharing the `$HOME` ignored it and listed it as `[other host: <name>]`,
+  `/cron set <ref> --host here|-` and `/triggers set --host` re-homed it, `cron_list` printed
+  `other_host:`, the leader and next-runs files were named `scheduler.<host>.json` and
+  `next-runs.<host>.json`, and an imported archive was re-stamped for the importing machine. None
+  of it matches the way pi-loops is used: pi runs on one machine, the loops run
+  there, and a phone or a laptop reaches the browser front end over a tailnet without moving the
+  execution anywhere. All of it is gone. A `host` field an older build left in `jobs.json`,
+  `triggers.json` or a `.pisession` archive is ignored when read and dropped on the next write; the
+  leader file is `scheduler.json`, the next-runs file `next-runs.json`. Two machines syncing one
+  `$HOME` now both run every job — not supported, and said so rather than half-handled
+  (`docs/design.md` §19). "Host" means one thing here now: the headless process.
+
+## [0.18.0] - 2026-09-14
+
+### Added
+- **Recipes: a project run on loops, installed in one command.** A recipe is a directory —
+  `recipe.toml`, one playbook per job, an optional setup script — and `/recipe add <name>` installs
+  it into the open project: one question (the autonomy level, `report` / `propose` / `act`, written
+  as the first line of each playbook), one confirmation showing every file, the setup script and
+  every `/cron add` line, then the jobs through the same code path `/cron add` uses. The playbooks
+  are copied to `.agents/skills/<name>/` — where pi also discovers them as `/skill:` commands — and
+  the directory is listed in `.git/info/exclude`, so the repository is untouched; a job's prompt is
+  a pointer to its playbook, read fresh on every run, so editing the file changes the next run.
+  `/recipe update` is a three-way merge against the untouched copy kept at install (under `.orig/`), and a conflict
+  is handed to the agent to resolve with you rather than left as markers in a file a loop would
+  follow. `/recipe remove` takes the jobs and leaves the files unless `--purge`. Each `[[job]]` in a
+  manifest is validated by building the `/cron add` line it stands for and parsing it with the same
+  parser. The one step no template can do — describing this project's tracker — is handed to the
+  session with the prompt in `recipes/_tracker-setup.md`, the way `/inbox claim` hands over a
+  finding, written to `docs/agents/issue-tracker.md` in the layout Matt Pocock's engineering
+  skills use and excluded from the repository like the playbooks — and the wizard resumes on its
+  own once that turn ends with the file in place. `pi-loops recipe list|show|add` in a shell does the deterministic part and stops
+  before the setup script and the jobs. `docs/recipes.md`; vocabulary in `CONTEXT.md`, decisions in
+  `docs/design.md` §15–18.
+- **Two recipes.** `issue-loop`: the tracker as a state machine (Matt Pocock's five triage states
+  plus `agent-working`, `in-review`, `agent-blocked`) that two loops turn, a triage loop that
+  reproduces, checks `.out-of-scope/` and writes agent briefs, and an implement loop that claims
+  one issue per run, builds it in a worktree and opens the pull request; a person promotes and
+  merges. `autoresearch`: one experiment per run against a `RESEARCH.md` contract you wrote, a
+  `results.tsv` ledger where retired ideas stay as negative evidence, a worktree per experiment,
+  and promotion only when the `--verify` checker has re-run the held-out command itself; with a
+  pure-Python exact k-NN example whose baseline is a speedup of 1.0. `changelog-draft` is packaged
+  as the release-side half of the issue loop.
+
+### Fixed
+- **The browser front end reported a slash command as timed out while it waited in a dialog.** A
+  `/…` prompt is answered by pi when the command has finished, and a command that shows a setup
+  script and asks for a yes finishes when the person answers; sixty seconds later the feed said
+  `timed out after 60000ms` and the install went on to succeed. A slash command now gets fifteen
+  minutes; everything else keeps sixty seconds.
+
 ## [0.17.6] - 2026-09-14
 
 ### Added

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.17.6    # or from GitHub, at a pinned tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.19.2    # 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
 ```
@@ -138,6 +138,11 @@ 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 two 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 — each a directory of playbooks copied into the project, installed with one question and one
+confirmation ([docs/recipes.md](docs/recipes.md)).
+
 Two that are not loops:
 
 ```text
@@ -263,7 +268,7 @@ State stays in `~/.pi/agent/loops` until you delete it.
 
 | Command | What it does |
 |---|---|
-| `/cron add [--stateful] [--verify] "<schedule>" <prompt>` | Schedule a job: plain jobs inject their result into this chat, `--stateful` makes a loop with memory and inbox routing, `--verify` adds the checker |
+| `/cron add [--stateful] [--verify] "<schedule>" <prompt>` | Schedule a job: a plain job belongs to this chat and injects its result here (it sleeps while this session is not open), `--stateful` makes a loop that runs wherever the clock is, with memory and inbox routing, `--verify` adds the checker |
 | `/cron`, `/cron all` | This project's jobs, or every project on this machine |
 | `/cron enable\|disable\|remove <ref>` | Pause, resume or delete one job — and write an audit entry into the session, as `add` does |
 | `/cron disable --all` | Pause every job in this project (`--all-projects` for the machine); `/cron enable --all` resumes |
@@ -284,11 +289,12 @@ State stays in `~/.pi/agent/loops` until you delete it.
 | `/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 |
 | `/triggers run <id>` | Check one rule now instead of waiting for its poll slot |
-| `/triggers set <id> --model\|--thinking\|--timeout\|--host` | Change what a rule runs with — the settings that decide how an unattended action behaves |
+| `/triggers set <id> --model\|--thinking\|--timeout` | Change what a rule runs with — the settings that decide how an unattended action behaves |
 | `/triggers sources`, `/triggers hooks` | Every source feeding the trigger runtime: each connected MCP server, whose notifications can fire a rule; the local crontab; the dynamic checker |
 | `/triggers panel [on\|off]` | The same panel, toggled from the trigger side |
-| `/session-export [path]`, `/session-import <path>` | Portable `.pisession` archive: transcript + jobs + rules + loop state |
+| `/session-export [path]`, `/session-import <path>` | Portable `.pisession` archive: transcript + jobs + rules + loop state (in the browser front end, `/session export` and `/session import` too; `/sessions` lists) |
 | `/session-share [--public]` | Upload a redacted transcript as a GitHub gist via `gh`, after showing you what it contains. (pi has its own `/share`, which sends the raw session elsewhere first — see [docs/session-archive.md](docs/session-archive.md)) |
+| `/recipe [list\|show\|add\|update\|remove <name>]` | Install a packaged way of running this project on loops — the issue tracker as a state machine, or one research experiment per run — with one question and one confirmation ([docs/recipes.md](docs/recipes.md)) |
 | `/pi-loops [install-launcher]` | Version and paths; `install-launcher` puts the `pi-loops` command on your `PATH` |
 
 A schedule is a 5-field cron expression, or one of `hourly` / `daily` / `weekly` (also `每天`), or
@@ -317,6 +323,7 @@ notifications, and lifecycle hooks — each has a page here.
 - [docs/mcp.md](docs/mcp.md) — MCP notification sources and tool registration (`mcp.toml`)
 - [docs/hooks.md](docs/hooks.md) — lifecycle hooks (`hooks.toml`), including `run_start` / `run_end` for scheduled runs
 - [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/web-ui-parity.md](docs/web-ui-parity.md) — what the browser front end owes you, line by line
@@ -337,7 +344,7 @@ notifications, and lifecycle hooks — each has a page here.
 | `~/.pi/agent/loops/logs/pi-<pid>.log` | what each pi process's automation did |
 | `~/.pi/agent/loops/triggers.json`, `triggers-audit.jsonl` | dynamic rules and trigger audit |
 | `~/.pi/agent/loops/{config,mcp,hooks}.toml` | configuration |
-| `~/.pi/agent/loops/scheduler.<host>.json` | which pi process currently owns the timer |
+| `~/.pi/agent/loops/scheduler.json` | which pi process currently owns the timer |
 
 Set `PI_LOOPS_DIR` to relocate all of it. The notes are yours to edit when the agent got something
 wrong, and `logs/pi-<pid>.log` is the file to read after an overnight failure.
@@ -347,7 +354,7 @@ wrong, and `logs/pi-<pid>.log` is the file to read after an overnight failure.
 Scheduled work is only worth trusting if it survives you closing the editor. So "pi was restarted"
 is treated here as the normal case rather than the exception.
 
-Jobs are machine-global, recorded per host, and never expire. Any open pi can own the timer:
+Jobs are machine-global and never expire. Any open pi can own the timer:
 leadership is a file with a heartbeat, and when the process holding it exits or dies, the next tick
 in another window picks it up. A project's trigger checks run in a pi that is open in that project,
 so a result that belongs in a conversation lands in the right one. A tick a loop missed while

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.17.6    # 或者从 GitHub 装，钉住一个 tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.19.2    # 或者从 GitHub 装，钉住一个 tag
 pi install /path/to/pi-loops                                # 或者本地检出；本仓库里就是 pi install .
 ```
 
@@ -215,6 +215,19 @@ pi update --extensions                             # 对齐已安装的包
 
 任务在创建时就记下自己的目录和模型，所以它不绑在敲出它的那个窗口上。`--cwd` 让它在另一个检出里跑——绝对路径，或相对当前项目；这里没有 shell，`~` 不会展开。`--model` 把模型钉死，`/cron set <ref> --model -` 解钉。
 
+### 不用自己写的：recipe
+
+```text
+/recipe                    有哪些打包好的 recipe，这个项目装了哪些
+/recipe add issue-loop     把 issue tracker 跑成状态机：分诊成 agent brief、在 worktree 里实现、开 PR；推进和合并留给人
+/recipe add autoresearch   按你写的研究合同每次跑一个实验，账本记下每次尝试，只凭 held-out 数据提议晋升
+```
+
+一个 recipe 是一组 loop 加上它们各自每次 run 都会读的 playbook。安装只问一个问题（自治级别
+`report` / `propose` / `act`）、确认一次（每个要写的文件、setup 脚本全文、每一行 `/cron add`），
+playbook 拷到 `.agents/skills/<name>/`，通过 `.git/info/exclude` 排除在仓库之外——你随时可以改它，
+下一次 run 就照改后的做。见 [docs/recipes.md](docs/recipes.md)。
+
 ## 用法
 
 会话里的命令分几摊：`/cron` 管任务，`/inbox` 管分诊，`/goal` 管「做到什么算完」，`/triggers` 管不看钟的那些规则，`/session-share` 把这次会话脱敏后发出去。
@@ -228,7 +241,7 @@ pi update --extensions                             # 对齐已安装的包
 /cron  ·  /cron list|ls|status      本项目的任务，[stateful] 标记；/cron all 看整台机器
 /cron enable|resume|disable|pause|remove <n|id|name>
 /cron set <ref> …                   改已有任务而不换 id（笔记因此留着）：--prompt、--schedule，
-                                    以及 --model、--thinking、--timeout、--name、--host 这几个钉子（`-` 解掉）
+                                    以及 --model、--thinking、--timeout、--name 这几个钉子（`-` 解掉）
 /cron run 1                         立刻跑一次（once 跑完即删，every 的间隔从现在重算，cron 的下次不变；停用的普通任务会被拒绝）
 /cron state ci                      loop 的笔记（状态脊柱）
 /cron runs [ci]                     最近运行，最新在前
@@ -299,7 +312,7 @@ at 2026-09-08          → UTC 零点   ← 只给日期按 UTC，在北京就
 
 要表示时间就把时间写出来。另外 `in 10m` / `at` 在**创建那一刻**就被算成一个绝对时刻存下来，之后改时区不影响它；`every 30m` 是纯间隔，和时区、夏令时都无关。
 
-**跨机器的 loop**：没有 `host` 的任务会在任何共享这个 `$HOME` 的机器上跑——`/cron set <ref> --host -` 干的就是把 `host` 这个键从任务上摘掉。stateful loop 的笔记是模型自己写的自由文本，里面常有 watermark（「看到这里为止」），所以 prompt 会要求模型写时间时带上偏移。0.14.1 之前写下的笔记没有这个保障，跨时区又带 watermark 的 loop 值得用 `/cron state <id>` 看一眼。
+**一台机器**：pi-loops 在运行 pi 的那台机器上跑，没有跨机器的概念（0.19.0 去掉了任务上的主机名戳；两台机器同步一个 `$HOME` 会各跑一遍，不支持）。要在别处看它，走 tailnet 开浏览器前端。stateful loop 的笔记是模型自己写的自由文本，里面常有 watermark（「看到这里为止」），而机器的时区会变（设了 `TZ`、带着笔记本出差、容器重建成 UTC），所以 prompt 会要求模型写时间时带上偏移。0.14.1 之前写下的笔记没有这个保障，时区变过又带 watermark 的 loop 值得用 `/cron state <id>` 看一眼。
 
 ## Maker/checker：先质疑每条 finding，再给你看
 
@@ -473,8 +486,8 @@ Output protocol (mandatory):
 
 定时任务值不值得信，取决于你关掉编辑器之后会发生什么。所以这里把「pi 重启过」当成常态：
 
-1. **任务是机器全局的（按主机）**，存在 `~/.pi/agent/loops/jobs.json`，不绑会话、不绑目录（每个任务记住自己的 `cwd` 与 `host`，子代理在那里跑；共享 $HOME 的另一台机器会忽略它）。任何目录里打开的任何 pi 都能看到并执行 stateful 任务；普通任务因为要注入对话，只在创建它的那个会话里触发（`--resume` 回来就继续），会话没了，leader 会把它停用，`/cron gc` 清掉；子代理创建的普通任务归它所服务的那个父会话。
-2. **loop 归本机唯一的 leader 跑；动态检查归「开在那个项目里的那个 pi」跑。** `scheduler.<host>.json` 里放 pid 加心跳，30 秒一 tick；leader 退出或者崩了，其它 pi 在下一 tick 接手。
+1. **任务是机器全局的**，存在 `~/.pi/agent/loops/jobs.json`，不绑会话、不绑目录（每个任务记住自己的 `cwd`，子代理在那里跑）。任何目录里打开的任何 pi 都能看到并执行 stateful 任务；普通任务因为要注入对话，只在创建它的那个会话里触发（`--resume` 回来就继续），会话没了，leader 会把它停用，`/cron gc` 清掉；子代理创建的普通任务归它所服务的那个父会话。
+2. **loop 归本机唯一的 leader 跑；动态检查归「开在那个项目里的那个 pi」跑。** `scheduler.json` 里放 pid 加心跳，30 秒一 tick；leader 退出或者崩了，其它 pi 在下一 tick 接手。
 
    每个进程每 tick 往 `presence/` 登记自己的 pid、会话和 cwd。一个项目的规则检查和推送评估，就交给开在那个项目里的 pi——优先创建规则的那个会话，其次 pid 最小的那个——所以 promote_to_chat 一定落在对的对话里。项目里一个 pi 都没开，才轮到 leader 代跑，结果进 inbox。
 
@@ -503,7 +516,7 @@ Output protocol (mandatory):
 | `~/.pi/agent/loops/spend.json` | 轮转掉的那部分花费按天留一份，预算上限不会因为 run log 被截断而失效 |
 | `~/.pi/agent/loops/logs/pi-<pid>.log` | 每个 pi 进程的自动化诊断，超 2 MB 保留后半，只留最近五个进程（进程还活着的那份不算） |
 | `~/.pi/agent/loops/sessions/<id>/*.jsonl` | 子代理完整 transcript，每个 loop 保留最近 20 份 |
-| `~/.pi/agent/loops/scheduler.<host>.json` | 当前 leader 的 pid / 心跳（每台机器一份） |
+| `~/.pi/agent/loops/scheduler.json` | 当前 leader 的 pid / 心跳 |
 | `~/.pi/agent/loops/triggers.json` | 动态 trigger 规则（全局，带 cwd） |
 | `~/.pi/agent/loops/triggers-audit.jsonl` | trigger audit，超 2 MB 保留后半 |
 | `~/.pi/agent/loops/sessions/triggers-<项目>-<哈希>/*.jsonl` | 动态检查子代理的 transcript，每个项目一个目录（目录名带项目路径的哈希，同名的两个项目不会共用），保留最近 40 份 |

package/docs/agents/issue-tracker.md

@@ -0,0 +1,34 @@
+# Issue tracker: GitHub
+
+Work items for this repository live as GitHub Issues in `alphacoder-v0/pi-loops`; pull requests
+are the review surface. Use the `gh` CLI for every operation; it infers the repository from the
+remote when run in a clone. Loops shell out to `gh`, so the account must be authenticated in the
+environment a loop runs in — `gh auth status` answers that.
+
+## Operations
+
+- **List**: `gh issue list --state open --limit 200 --json number,title,labels,updatedAt,author` (add `--label <state>` to filter by state)
+- **Read**: `gh issue view <n> --comments --json number,title,body,labels,author,createdAt,comments`
+- **Comment**: `gh issue comment <n> --body "..."` (a heredoc for multi-line bodies)
+- **Change state**: `gh issue edit <n> --add-label "<new state>" --remove-label "<old state>"` — exactly one state label at a time
+- **Claim**: `gh issue edit <n> --add-label agent-working --remove-label ready-for-agent --add-assignee @me`
+- **Close**: `gh issue close <n> --comment "..."`
+- **Pull requests**: `gh pr create`, `gh pr list --state open --json number,url,headRefName,reviewDecision,comments,updatedAt`, `gh pr view <n> --comments`, `gh pr diff <n>`
+
+## State vocabulary
+
+One category label (`bug` | `enhancement`) and exactly one state label per open issue. The state
+labels are `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `agent-working`,
+`in-review`, `agent-blocked`, `wontfix`. They already exist in this repository; `labels.sh`
+refreshes their colour and description and touches no issue. A playbook that moves an issue names
+the label it moves to.
+
+## Blocking
+
+A `Blocked by: #<n>, #<m>` line near the top of an issue body (or the tracker's native
+dependency) gates it: the item is unblocked when every listed issue is closed.
+
+## Who counts as the agent
+
+Comments and assignments made by loops are made as the account `gh` is signed in as — currently
+`alphacoder-v0`. Every comment a loop posts starts with a line saying it was generated by AI.

package/docs/cli.md

@@ -213,8 +213,12 @@ pi-loops host status | abort <run-id|trace-id> | stop
 
 ## sessions, inspect
 
-`sessions` lists the ids `export --session` accepts, newest first — without it an unknown id was
-the only error you could get. `inspect` prints an archive's schedules, prompts and rules without
+`sessions` lists this project's sessions newest first, one line each: the first sixteen
+characters of the id, when the session started, the automation it
+has (`[2 cron, 1 trigger]`, or `[automation off]` when all of it is disabled), and what was first
+said in it — the session's name if it was given one, otherwise the first message, cut at eighty
+characters. `--all` lists every project and puts the cwd after the id. The id is what
+`export --session` accepts; a unique prefix will do. `inspect` prints an archive's schedules, prompts and rules without
 writing anything, which is what you want before restoring on a machine you care about.
 
 ## export
@@ -260,3 +264,19 @@ accepted). `host stop` ends the host; the next pi to open would have taken the c
 
 The channel is a unix socket at `host.sock` in the loops directory, created 0600, and it is
 read-mostly on purpose: a host you could prompt would be a second chat.
+
+## recipe
+
+```sh
+pi-loops recipe list                       # the packaged recipes, and which are installed in this directory
+pi-loops recipe show issue-loop            # its files, jobs, levels, setup script
+pi-loops recipe add issue-loop [--cwd <dir>] [--level report|propose|act] [--overwrite]
+```
+
+`add` is the deterministic half of `/recipe add` ([recipes.md](recipes.md)): it copies the
+playbooks to `.agents/skills/<name>/`, lists that directory in `.git/info/exclude` and writes the
+record — and stops. The setup script and the jobs need a pi open in the project: `/recipe add
+<name>` there finds the copies in place, shows the script and the `/cron add` lines, and creates
+them after you say yes. Without `--level` the lowest level the recipe supports is written; an edited
+copy is kept unless `--overwrite` says otherwise.
+

package/docs/configuration.md

@@ -15,7 +15,7 @@ Everything lives under `~/.pi/agent/loops/` (override: `PI_LOOPS_DIR`).
 | `runs.jsonl`, `triggers-audit.jsonl` | run log (halved past 1 MB) and trigger audit (2 MB) |
 | `spend.json` | per-day totals of what rotation dropped from the run log, so a daily budget still counts it |
 | `sessions/<job-id>/`, `sessions/triggers-<project>-<hash>/` | sub-agent transcripts (20 per job, 40 per project's checks; the hash of the project's path keeps two projects named alike apart) |
-| `scheduler.<host>.json` | timer owner on this host: pid, heartbeat |
+| `scheduler.json` | timer owner on this machine: pid, heartbeat |
 | `presence/` | one file per live pi process: pid, session, cwd (who acts for which project) |
 | `host.json`, `host.log` | the headless host that keeps the clock while no pi is open: pid, and its log |
 | `polls.json` | last dynamic check per project (shared, so a hand-over never double-checks) |

package/docs/design.md

@@ -24,19 +24,21 @@ The premise is that **"pi was restarted" is the normal case**. Automation that d
 it was configured in is automation you cannot rely on, so jobs and rules live on disk for the whole
 machine. Everything here follows from that, and each one has a price.
 
-1. **Machine-global jobs and rules, each carrying a `cwd` and a `host`.** `/cron` and
+1. **Machine-global jobs and rules, each carrying a `cwd`.** `/cron` and
    `/triggers rules` show the current project by default, and say how many are elsewhere. A plain
-   (inject) job belongs to the session that created it: listed as `[dormant …]` while that session
-   is not open, parked as disabled once the session no longer exists (`/cron gc` removes it). A loop
+   (inject) job belongs to the session that created it — its result is a message in that
+   conversation — and everything that lists it agrees with dispatch about that: another session
+   shows it as `[session <id> — resume it to run]` with no next run, `cron_list` says the same to
+   the model, `/cron run` refuses it. Asleep is not broken. It is parked as disabled only once its
+   session's file has been deleted (`/cron gc` removes it). A loop
    whose `cwd` disappeared waits half an hour — a mount can be late at boot — and is disabled after
-   that. Jobs and rules stamped with another host (a shared `$HOME`) are ignored here and listed
-   with whose they are; leader election is per host.
+   that.
 
    The cost: a list has to be scoped, and a job you cannot see reads as a job that is gone. Hence
    the counts, the markers, and `/cron all`.
 
 2. **Who runs what.** Every process ticks. Loops run in the machine leader
-   (`scheduler.<host>.json`, a pid and a heartbeat). A project's dynamic checks and push
+   (`scheduler.json`, a pid and a heartbeat). A project's dynamic checks and push
    evaluations run in a pi that is *open in that project* — preferring the session that created the
    rules, lowest pid otherwise (`presence/`) — so a promotion lands in the conversation it belongs
    to. Only a project with no pi open falls to the leader, and its results go to the inbox
@@ -117,6 +119,61 @@ machine. Everything here follows from that, and each one has a price.
     failed — the slot is still owed and the failure streak does not advance. Diagnostics go to
     `logs/pi-<pid>.log` rather than only to a chat notification that a new session erases.
 
+15. **Recipes are files, not code.** A recipe (`CONTEXT.md` has the vocabulary) is a directory:
+    a `recipe.toml` manifest whose `[[job]]` fields are the arguments of `/cron add` and nothing
+    else, one playbook per job, an optional setup script. Anything the wizard does with one is
+    something a person could have done by hand with `/cron add` and `cp`. The first catalogue is
+    seven: issue-loop, daily-digest, changelog-draft, pr-watch, ci-sweeper, autoresearch, and
+    ecosystem — the last capped at `propose`, because every outward word it drafts is a finding a
+    person claims before it is said.
+
+    The cost: a project cannot add a recipe by writing TypeScript, only by writing a directory,
+    and the wizard can only ask what a manifest can declare.
+
+16. **Playbooks are copied into the project and kept out of its history.** `/recipe add` copies
+    them to `<project>/.agents/skills/<recipe>/` — where pi also discovers them as `/skill:`
+    commands, so a person can run one step by hand — and lists the directory in
+    `.git/info/exclude`, so the repository is not touched. A loop's prompt is a pointer to that
+    file; the procedure is read fresh on every run. The tracker description the playbooks read
+    (`docs/agents/issue-tracker.md`, in the layout Matt Pocock's engineering skills use, so a
+    repository that has those reads the same file) is excluded the same way: it names an account
+    and a workflow, which are the project's to keep and not the repository's to publish.
+
+    The cost: two clones of one project each install the recipe, and a playbook edited on one
+    machine is not on the other. Upgrading pi-loops upgrades the packaged recipes, not the copies:
+    `/recipe update` is a three-way merge against the untouched copy kept at install (under
+    `.orig/` beside the playbooks), silent when the person changed nothing, and conflicts are handed to the
+    session as a prompt to resolve with the person rather than left as markers in a file the next
+    run will read.
+
+17. **The wizard is deterministic; one step is not.** Choosing a recipe, its autonomy level, the
+    copy and the `/cron add` lines run with no model and end in a confirmation that shows exactly
+    what will be created. The one thing a template cannot do — describe *this* project's tracker —
+    is handed to the running session with `sendUserMessage`, the way `/inbox claim` hands over a
+    finding: explore the remote, propose, confirm, write the file — and when that turn settles with
+    the file there, the wizard resumes by itself, so the command is typed once. `pi-loops recipe`
+    in the terminal does the deterministic part only.
+
+18. **One autonomy dial, three positions, in prose.** `report` reads and files findings; `propose`
+    may also write to the tracker and open draft pull requests but never reach a terminal state;
+    `act` may. A manifest declares which positions a recipe supports, the wizard defaults to the
+    lowest, and the chosen one is a line at the top of each playbook — text the model reads and a
+    person edits, enforced by nothing in code. The cost is exactly that: the level is an instruction,
+    not a permission, and the permissions that exist (the danger policy, the daily budget, branch
+    protection on the remote) are the ones that hold.
+
+19. **One machine.** Until 0.19.0 every job and rule carried the hostname that created it, another
+    machine sharing the `$HOME` ignored it and listed it as `[other host]`, `/cron set --host`
+    re-homed it, and the leader file was named per host. None of it matched the way pi-loops is
+    used: pi runs on one machine, the loops run there, and a phone or a
+    laptop reaches the browser front end over a tailnet (`tailscale serve`) without moving the
+    execution anywhere. So the concept is gone: no `host` on a job or a rule (a stamp an older
+    build left is dropped when the file is read), no `--host`, no marker, `scheduler.json` and
+    `next-runs.json` plain. "Host" now means one thing here, the headless process.
+
+    The cost: two machines syncing one `$HOME` both run every job. That is not supported, and it
+    is said rather than half-handled.
+
 ## Where the browser front end came from
 
 pi owns the `pi` command and its terminal, so a second front end cannot replace the first one. It

package/docs/loops.md

@@ -10,8 +10,14 @@ Everything here is `/cron`; `/crontab` and `/loop` are the same command under ot
 
 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. Plain jobs fire only from the process whose current
-session created them; `--resume` brings that back.
+is busy the message is queued as a follow-up. 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.
 
 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 * * *`;
@@ -106,8 +112,8 @@ and answer with one `<verdict n="i">keep|drop — reason</verdict>` per finding
 
 ## Restart behavior
 
-Jobs live in `~/.pi/agent/loops/jobs.json` and survive pi restarts. Exactly one pi process per
-host owns the timer (`scheduler.<host>.json`, 30-second ticks, 90-second heartbeat); when it exits
+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
@@ -116,12 +122,15 @@ loops). A run that died with its process is retried on the next tick; at most
 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 jobs as `[dormant …]` when their session
-is not open here, parks them as disabled once that session no longer exists (`/cron gc` removes
-them), and `[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. A job
-stamped with another machine's hostname (a synced `$HOME`, a renamed machine, a rebuilt container) is listed as
-`[other host: <name>]` with no next run; `/cron set <ref> --host here` re-homes it.
+`/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.
+
+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
+reach a running pi from elsewhere, use the browser front end over your tailnet ([cli.md](cli.md));
+the loops keep running where pi runs.
 
 ## Time, and which clock it is
 
@@ -147,14 +156,13 @@ Two things are deliberately still UTC, because neither is a time anybody reads:
 session file, which cannot hold the `+` and `:` an offset brings, and pi's own session header, whose
 format is pi's to decide.
 
-The offset in the run line above is the offset of **the machine that ran it**, not a fixed part of
-the prompt. That matters for one case in particular: a job with no `host` runs on any machine
-sharing the `$HOME` (`/cron set <ref> --host -` asks for that), so a stateful loop can alternate
-between machines in different timezones. Its notes are free text the model writes — watermarks,
+The offset in the run line above is the offset of the machine **at the time it ran**, not a fixed
+part of the prompt. A machine's clock is not a constant: `TZ` gets set, a laptop travels, a
+container is rebuilt in UTC. A loop's notes are free text the model writes — watermarks,
 "everything up to here has been seen" — and a watermark without an offset is a watermark the next
-machine cannot read. The prompt asks for the offset for that reason. Notes written before this
-version do not have it; a loop that crosses timezones and keeps a watermark is worth one look at
-`/cron state <id>`.
+run cannot read once the clock has moved. The prompt asks for the offset for that reason. Notes
+written before 0.14.1 do not have it; a loop that keeps a watermark on a machine whose timezone has
+changed is worth one look at `/cron state <id>`.
 
 ### Daylight saving