@alphacoder-v0/pi-loops 0.17.3

package/docs/hooks.md

@@ -0,0 +1,110 @@
+# Lifecycle hooks
+
+`~/.pi/agent/loops/hooks.toml`; a
+`hooks.toml` works verbatim.
+
+```toml
+allow_project_hooks = false        # also: config.toml, or PI_ALLOW_PROJECT_HOOKS=1
+
+[[hook]]
+event = "tool_end"                  # agent_start agent_end run_start run_end turn_start turn_end
+tool = "bash"                       # message_start message_update message_end tool_start tool_update tool_end compaction
+command = "echo \"$PI_TOOL_NAME error=$PI_TOOL_IS_ERROR\" >> ~/tool-hooks.log"
+timeout_ms = 3000                   # default 5000
+cwd = "project"                     # project | loops | home
+on_failure = "warn"                 # warn | ignore
+
+[[hook]]
+event = "turn_end"
+webhook = "https://example.com/hooks"
+[hook.headers]
+Authorization = "Bearer your-token"
+```
+
+- Commands run through `sh -c` with `PI_*` variables (`HOOK_EVENT`, `HOOK_PAYLOAD`
+  → path of a JSON file, `SESSION_ID`, `CWD`, `MODEL_PROVIDER`, `MODEL_ID`, `THINKING_LEVEL`,
+  `MESSAGE_KIND`, `ASSISTANT_EVENT`, `TOOL_CALL_ID`, `TOOL_NAME`, `TOOL_IS_ERROR`,
+  `COMPACTION_TRIGGER`, `COMPACTION_TOKENS_BEFORE`, `COMPACTION_FAILED`), set only when they have
+  a value. `cwd = "loops"` runs the command in `~/.pi/agent/loops`.
+- What a hook prints on **stdout** is written to this process's log, `~/.pi/agent/loops/logs/pi-<pid>.log`,
+  as `hook <source> <event>: <output>` — redacted and rotated like everything else there, and cut
+  off after 4000 characters so a chatty hook cannot rotate away the night's history. `echo` and
+  read the file is the usual way to find out what a hook did. stderr is still kept for the failure
+  message only. The headless host does the same into `host.log`, which is where the question is
+  usually asked.
+- Webhooks receive `Content-Type: application/json` with a payload whose every field is always
+  present, `null` when it does not apply. `message_kind` is `user` | `assistant` | `tool_result`
+  | the custom message's type. Summaries are truncated to 2000 characters and not redacted (they
+  are your own scripts).
+
+  ```json
+  {"event": "tool_end", "session_id": "…", "cwd": "/path/to/repo", "model_provider": "openai",
+   "model_id": "gpt-5.5", "thinking_level": "off", "source": "user", "message_kind": null,
+   "message_summary": null, "assistant_event": null, "tool_call_id": "call_…", "tool_name": "bash",
+   "tool_is_error": false, "tool_args": {"command": "ls"}, "tool_result_summary": "…",
+   "compaction_trigger": null, "compaction_tokens_before": null, "compaction_summary": null,
+   "compaction_failed": null}
+  ```
+
+- `message_update` fires for every streamed delta; use it only when you really need
+  streaming-level callbacks. `compaction` carries a truncated summary of your conversation
+  (`compaction_trigger` = `auto` | `manual`, `compaction_tokens_before`); send it only to
+  destinations you trust.
+- `compaction` also fires when a compaction **failed or was cancelled**, with
+  `compaction_failed: true` (`$PI_COMPACTION_FAILED`) and no summary or token count — nothing was
+  written. This is the case a watcher most wants: a session
+  that cannot compact is a session about to fail on context length. A hook that only cares about
+  successful compactions should test it:
+
+  ```toml
+  [[hook]]
+  event = "compaction"
+  command = 'if [ "$PI_COMPACTION_FAILED" = true ]; then notify-send "compaction failed" "$PI_SESSION_ID"; fi'
+  ```
+- Rules for one event run sequentially in file order and are awaited inline, so
+  a hook always finishes before the agent moves on and nothing is lost at exit. `[hooks] mode =
+  "async"` in `config.toml` queues them off the turn instead (then shutdown waits up to 3 seconds).
+  A timeout or Ctrl-C kills the whole process tree. Failures warn (or are ignored per rule) and never
+  fail a turn.
+- A malformed rule is skipped with a diagnostic; the rest of the file still loads. Project hooks
+  (`<project>/.pi/hooks.toml`) are ignored unless allowed.
+  Without a UI (`pi -p`) hook failures go to stderr.
+
+## Exactly when hooks fire
+
+- **`agent_*`, `turn_*`, `message_*`, `tool_*` and `compaction` are about a conversation.** The pi
+  you are talking to fires them. Sub-agent sessions — loop runs, checkers, trigger checks — fire
+  nothing: they are not the session you are in.
+- **`run_start` and `run_end` are about a scheduled run**, and they fire wherever the run happens:
+  in the pi you are talking to, and in the headless host ([loops.md](loops.md)). Whether a 3am job
+  ran under a host or under a pi you left open is an accident of who held the clock, and a hook rule
+  should not be able to tell.
+
+  They exist because a scheduled run is not a turn. It happens with no conversation at all, or
+  beside one — and overloading `agent_*` would mean a rule you wrote about your own turns quietly
+  started firing for automation.
+
+  Dynamic trigger checks and MCP pushes fire no hooks: they poll, and a hook on every poll is noise,
+  not news.
+- The `run_*` payload describes the run. Alongside the usual fields it carries `run_job` (the job's
+  name or id), `run_id`, and on `run_end` also `run_ok`, `run_findings`, `run_error` and
+  `run_cost_usd` — each as `$PI_RUN_JOB`, `$PI_RUN_OK` and so on. So "tell me when a loop fails" is:
+
+  ```toml
+  [[hook]]
+  event = "run_end"
+  command = '[ "$PI_RUN_OK" = false ] && notify-send "loop $PI_RUN_JOB failed" "$PI_RUN_ERROR"'
+  ```
+
+  In the host, where there is no conversation, `session_id` is the run id and `cwd` — including any
+  `cwd = "project"` rule — is the job's directory.
+
+- `run_*` hooks are always queued off the run, whatever `[hooks] mode` says, in both processes — a
+  webhook that hangs must not hold up the clock, and the run it announces has already started or
+  already finished. `mode = "sync"` is about ordering within a conversation turn, and a run is not
+  one. The host drains for up to 3 seconds when it exits. Failures go to the host log,
+  `~/.pi/agent/loops/host.log`.
+
+- Project hooks in the host additionally need the job's cwd to be a directory you trusted in pi
+  (that exact directory, not an ancestor): a job's cwd can be chosen by a model, and nobody is
+  there to answer a trust prompt.

package/docs/loops.md

@@ -0,0 +1,315 @@
+# Cron jobs, stateful loops, the inbox, maker/checker
+
+Everything here is `/cron`; `/crontab` and `/loop` are the same command under other names.
+
+## Plain cron jobs
+
+```text
+/cron add "*/30 * * * *" summarize the repo state
+```
+
+When due, the prompt is injected into the session that created the job as a user message with the
+engine prefix `[Trigger <run-id>] `, and the agent runs one turn (an *inject-and-run* job). If the agent
+is busy the message is queued as a follow-up. Plain jobs fire only from the process whose current
+session created them; `--resume` brings that back.
+
+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 * * *`;
+`weekly` → `0 9 * * 1`; `每小时`, `每天`, `每周`), and crontab's `@hourly` / `@daily` / `@weekly` /
+`@monthly`. `daily` means 09:00 local; `@daily` means midnight. Also `every 30m`, `in 10m` and
+`at 2026-09-08T18:00` (one-shot jobs are removed after they fire).
+
+## Stateful loops
+
+```text
+/cron add --stateful "0 9 * * *" check the repo issues and report anything new since the last run
+```
+
+Each run is a fresh sub-session inside the interactive pi, through pi's SDK: full tools including the parent's live MCP servers, the session's model and thinking
+level, no conversation history, its own transcript file. Every run gets the same prompt: the output
+protocol, preceded by one line of context (the job's name, when the run started, whether it is a
+catch-up):
+
+```text
+You are running the recurring loop "<name>" (current run started <when it started, on the clock of the machine running it, with that machine's offset>; write any time in your notes with its offset, as that one has). This is a background run: nobody is watching, and your final reply is parsed by a program.
+
+[loop-state] (your notes from the previous run of this recurring job)
+<contents of the state file, or "(first run)">
+[/loop-state]
+
+<your prompt>
+
+Output protocol (mandatory):
+- End your reply with <loop-state>notes for the next run</loop-state> — it REPLACES the saved state; keep it under 2000 characters and make it the information your next run needs (baselines, ids already seen, watermarks).
+- For each finding a human should act on, emit <inbox>one concise line</inbox>. No findings → no inbox tags; do not invent work.
+- Keep everything after the last tool call short so the tags are not truncated.
+```
+
+Then:
+
+- the last `<loop-state>` block replaces `state/<id>.md` (capped at 2000 characters);
+- up to 16 `<inbox>` tags (each ≤500 characters) are appended to the inbox; extras are counted as dropped
+  — the count is exact up to the first 1000 tags, past which a reply is a runaway rather than a report;
+- missing or malformed tags never fail a run: the state stays untouched, nothing enters the inbox;
+- a run that is still going when the next tick arrives is skipped and counted (`skipped overlaps`).
+
+Every run leaves a trail: the sub-agent's full transcript (`/cron trace <job> [k]`, 20 per job), a
+run log with exit code, duration, cost and finding counts (`/cron runs`), and a card in the
+transcript when the run finishes. Prompts are capped at 8 KB.
+
+## 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.
+
+```text
+/inbox                 Inbox (<project>, N new, 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]
+```
+
+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
+the third line of *this* project's list, never another repository's finding run in this directory —
+while an id or an id prefix still resolves machine-wide. `/inbox clear` dismisses what it listed,
+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
+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
+the checker carry a `✓`.
+
+## Maker/checker (`--verify`)
+
+With `--verify` (implies
+`--stateful`; `--checker-model provider/id` picks another model) the maker's findings do not go to
+the inbox directly. A second sub-agent receives the loop goal, the maker's notes and the numbered
+findings and is told to assume each may be wrong, stale, duplicated or trivial, verify with tools,
+and answer with one `<verdict n="i">keep|drop — reason</verdict>` per finding (plus an optional
+`<rewrite n="i">…</rewrite>`).
+
+- Kept findings enter the inbox marked verified; the checker's reason travels with the claim.
+- Dropped findings and their reasons go to the run log and the run card; `/cron trace <job> <k> checker` shows the checker's transcript.
+- Findings without a verdict enter unverified.
+- **Fail-open:** if the checker fails or times out, every finding enters the inbox marked unverified. A broken checker must not silence the loop.
+- The checker never touches the state spine.
+
+## Restart behavior
+
+Jobs live in `~/.pi/agent/loops/jobs.json` and survive pi restarts. Exactly one pi process per
+host owns the timer (`scheduler.<host>.json`, 30-second ticks, 90-second heartbeat); when it exits
+or dies another open pi takes over on its next tick. A tick that was missed while no pi was running
+is fired once at startup (collapsed, not replayed) for stateful loops unless `[cron] catch_up = false`;
+plain inject jobs do not catch up unless created with `--catchup` (`--no-catchup` turns it off for
+loops). A run that died with its process is retried on the next tick; at most
+`[cron] max_concurrent_runs` (3) run at once. Trigger checks share `[cron] max_concurrent_runs`, so
+a server pushing many distinct events cannot open one sub-agent per event.
+Jobs run with the model and thinking level recorded
+on them (`/cron set <id> --model … --thinking … --timeout …`, `-` to follow the running session).
+`/cron scheduler` shows who owns the timer; `/cron` marks 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.
+
+## Time, and which clock it is
+
+**Everything is this machine's clock.** Cron expressions are matched against local time — `0 9 * * *`
+is nine in the morning where the machine is, not 09:00 UTC — and there is no per-job timezone. Move
+the machine, or change its `TZ`, and the jobs move with it.
+
+Timestamps are written the same way, with the offset that makes them unambiguous — this is what a
+machine at `+08:00` writes; yours writes its own:
+
+```json
+{"startedAt": "2026-09-11T20:37:59.405+08:00", "finishedAt": "2026-09-11T20:38:12.880+08:00"}
+```
+
+That is the same instant `2026-09-11T12:37:59.405Z` names, and anything that parsed one parses the
+other — including what earlier versions wrote. The difference is that opening
+`runs.jsonl` shows the hour you were at your desk, and it agrees with the `next` on the `/cron` line
+that sent you there. `/cron` and `/inbox` say the offset in their header; a timestamp that travels
+somewhere without one — into a sub-agent's prompt, into a tool result a model reads — carries its
+own.
+
+Two things are deliberately still UTC, because neither is a time anybody reads: the name of a
+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,
+"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>`.
+
+### 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):
+
+| | what happens |
+|---|---|
+| Spring forward — `0 2 * * *` on 8 March | 02:00 does not exist that day, so the job **does not run**. It runs again the next day. |
+| Fall back — `0 1 * * *` on 1 November | 01:00 happens twice, so the job **runs twice**. |
+
+Vixie cron special-cases both (it runs a skipped job once, and a repeated one once). pi-loops does
+not: it matches the wall clock, and the wall clock is what it is. If a job must run exactly once a
+day whatever the clock does, `every 24h` is immune — it counts elapsed time and never consults a
+calendar.
+
+### `in` and `at`
+
+`every 30m` is an interval: no timezone, no DST, no wall clock at all.
+
+`in 10m` and `at <ISO time>` are resolved **once, when the job is created**, and stored as the
+instant they landed on. Changing the machine's timezone afterwards does not move them. Note what
+JavaScript does with the text you give `at`, which is the standard's rule rather than ours:
+
+```text
+at 2026-09-08T18:00    → 18:00 local
+at 2026-09-08T18:00Z   → 18:00 UTC
+at 2026-09-08          → midnight UTC   ← a date with no time is UTC, not local
+```
+
+Write the time if you mean a time.
+
+## Changing a job in place
+
+```text
+/cron set <ref> --prompt "check the CI and report only what changed"
+/cron set <ref> --schedule "0 9 * * 1-5"
+```
+
+The first version of a loop's prompt is always slightly wrong, and the fix used to be
+remove-and-re-add — which mints a new job id and leaves the loop's notes behind at the old
+`state/<id>.md`. `--prompt` and `--schedule` edit the job in place, so the id, the notes and the
+run history stay. Both values are one token: quote anything with spaces in it. Unlike the pins,
+neither takes `-` — a job always has a prompt and a schedule, so `-` would have nothing to fall
+back to and is refused rather than silently emptying the prompt (`--prompt "-"`, quoted, is the
+literal text). The previous wording goes to the loops log, so a loop that starts behaving
+differently can be traced to the edit that caused it.
+
+The new schedule is parsed before it is stored: a typo leaves the job untouched, and so does an
+expression that can never match (`0 0 30 2 *`). The confirmation prints the next run time, which is
+where a plausible-but-wrong expression shows itself. Changing the schedule does not backfill: a
+cron job's clock restarts at the edit, so slots that only exist retroactively under the new
+expression are not owed. An `every <dur>` job is still measured from its last run — if it last ran
+longer ago than the new interval, it is genuinely overdue and the confirmation says `due now`
+instead of promising a later time. One-shots (`in 10m`, `at <ISO>`) are refused here: the scheduler
+deletes a `once` job after it fires, notes included.
+
+`/cron run <ref>` fires a job now instead of at its next due time, and that run counts as a run: a
+`once` job is fired and then removed (an enabled job with nothing left to fire is worse than none),
+an `every <dur>` job's interval restarts from now, and a `cron` job's next run is unchanged — the
+expression says when it runs, not the last run. A disabled plain job is refused rather than run: its
+prompt would land in whichever chat is open now rather than the one it was written for, and a job the
+dead-session sweep parked has to keep the marker `/cron gc` collects it by.
+
+A project is matched by realpath and containment, so a pi opened in a subdirectory, a worktree or
+through a symlink sees and runs that project's automation.
+
+## What it costs, and capping it
+
+`/cron cost [today|7d|all]` adds up the run log by job, and shows today's spend against the budget
+if one is set. Every loop run, its checker and every trigger check is counted; so is the `/goal`
+evaluator.
+
+```toml
+[limits]
+daily_budget_usd = 5.0   # 0 (the default) means no cap
+```
+
+Once today's automation has cost that much, nothing more is dispatched: loop runs, plain jobs and
+trigger checks stop, the job's `last_error` says so, and the slot stays owed rather than being
+skipped, so work resumes when the day rolls over or the cap is raised. The run log is rotated by
+size, so what it drops is folded into a small per-day ledger first — a cap that forgot yesterday's
+busy morning would stop capping halfway through the day.
+
+The cap is also checked **while a run is in flight**, not only before it is dispatched: a run
+admitted at $4.99 of a $5.00 budget would otherwise be free to spend any amount, and three runs
+admitted in the same tick would each be free to. A run is measured once per model turn against
+today's recorded spend plus everything this process has in flight — its own cost so far, the runs
+beside it, and, with `verify = true`, the maker whose findings its checker is reviewing. When that
+total reaches the cap the run is stopped the way the run timeout stops one: pi aborts the
+sub-session and the run is recorded with what it had spent. It is treated as an interruption rather
+than as a job that failed — the concurrency slot is released, the tick stays owed, the job's
+failure streak is untouched and a one-shot is not retired — so the loop simply resumes when the day
+rolls over or the cap is raised, held back until then by the check at dispatch.
+
+A stopped run is a failed run in `/cron runs` and `/cron trace`, but never an unexplained one — its
+error is the reason, and the reason leads with the cap:
+
+```
+FAILED: stopped by today's $5.00 daily budget ($4.62 already spent, $0.41 in flight); raise…
+```
+
+The same line lands in the job's `last_error` and in the diagnostics log. A run stopped this way
+keeps its transcript, and its findings up to that point are not written to the inbox — the run did
+not finish, so its `<loop-state>` and `<inbox>` tags are not trusted.
+
+## Stopping, removing, and jobs that keep failing
+
+`/cron disable --all` pauses every job in this project (`--all-projects` for the machine) and
+`/cron enable --all` resumes them — quitting pi hands the clock to the host rather than stopping
+anything, so this is how you actually go quiet.
+
+If a loop is stuck showing `running` after a process was killed and its pid reused, `/cron clear
+<ref>` releases the marker (it asks first).
+
+`/cron remove` keeps the loop's notes (to change a prompt or a schedule, edit the job in place with
+`/cron set` instead); `--purge` deletes them. `/cron gc` collects this project's jobs whose session
+is gone — `--all` every project's, `--purge` also the loop state left behind by jobs that are gone.
+
+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.
+
+## When something looks wrong
+
+Every diagnostic a pi process produces is written to `logs/pi-<pid>.log` in the loops directory —
+jobs that were disabled, writes that failed, sub-agent warnings — so a loop that failed at 03:00
+still has something to read at 09:00. `/cron scheduler` prints the path. The headless host writes
+`host.log` the same way; both are rotated.
+
+`PI_LOOPS_DEBUG=1` adds a line per tool call, provider retry and compaction to that log, which is
+the quickest way to tell a stuck run from a busy one.
+
+`/cron snapshot` writes a `pi_loops_snapshot` entry into the session: which MCP servers connected
+and what they exposed, the active tools, the hooks, whether this pi owns the clock, the last
+check. One is written automatically whenever that state changes. The TUI panel shows the same
+thing; the entry is for a front end that is not a terminal — the browser one in
+[src/web.mjs](../src/web.mjs) reads it, and so can anything else that speaks to a session.
+
+`/triggers running` shows how long each run has been going and, for loop runs, the transcript that
+is being written right now (`pi --session <file>`), so "is it stuck or is it working" is answerable
+before the run ends. A run gets the tools the
+session that owns the clock has active (a job's `--tools` narrows that, never widens it), plus its
+own project's MCP servers, and the automation tools it calls act in its own project.
+
+An unattended run refuses a corpus of dangerous commands: sudo, `curl … | sh`, writing to a block
+device, `mkfs`, `chmod 777 /`, shutdown/reboot, `git push --force` on main/master, pipes into
+`eval`, the fork bomb, and `rm -r -f` aimed at `/`, an absolute path or `$HOME`. The model is told
+why and can do the safe part.
+
+When the last pi on the machine quits, it hands the clock to a headless host (`/cron host`): a
+small `node` process with the same stores and runner that keeps loops, trigger checks and MCP
+pushes going — findings still reach the inbox — until the next pi opens and takes the clock back.
+It is started only when there is work for it: an enabled loop or rule for this machine, or an MCP
+server whose pushes inject or have rules to match. `pi-loops host status` shows what it is doing
+while it runs, and `pi-loops host abort <id>` interrupts one run (see [cli.md](cli.md)). `[host] auto = false` turns that off;
+`/cron host start` hands off on quit anyway (this pi only), `/cron host stop` ends a running host
+and cancels the hand-off. `host.log` shows what it did; a host that died is reported by the next
+pi to open. After a reboot nothing runs until a pi opens (which hands off again when it quits).

package/docs/mcp.md

@@ -0,0 +1,90 @@
+# MCP: notification sources and tools
+
+pi has no built-in MCP client; pi-loops carries a small one (stdio and streamable HTTP) that consumes
+notifications and registers the servers' tools with pi.
+
+## Configuration
+
+`~/.pi/agent/loops/mcp.toml`, plus `<project>/.pi/mcp.toml` for trusted projects (same server
+name → project wins). The schema:
+
+```toml
+[[server]]
+name = "filesystem"                    # kind defaults to stdio
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+# env = { FOO = "bar" }                # extra environment for the server process
+
+[[server]]
+name = "hub"
+kind = "streamable_http"
+endpoint = "https://example.com/mcp"   # https required, 127.0.0.1 excepted
+auth = { kind = "bearer", token_keychain_ref = "PI_MCP_TOKEN_HUB" }  # pi's credential store, or a PI_MCP_TOKEN_* env var
+request_timeout_ms = 30000
+sse_idle_timeout_ms = 60000            # reconnect when the event stream goes silent
+body_cap_bytes = 1048576
+reconnect = { initial_ms = 500, max_ms = 30000, max_attempts = 10 }
+inject_summary = true                  # summary straight into the chat, no model call
+# inject_and_run = true                # summary into the chat + one agent turn
+```
+
+A misconfigured server is reported as `mcp server '<name>' failed: …`; the others still connect.
+stdio servers must not set `endpoint`/`auth`; timeouts, caps and reconnect delays must be positive;
+only bearer auth is supported.
+
+## Notifications → triggers
+
+Server pushes are mapped: `tools/resources/prompts listChanged` use stable
+keys and collapse to the latest event; `resources/updated` is keyed per URI; custom notifications
+need `_meta.pi_dedup_key` or are dropped at the source and counted. Summaries contain only the
+method name plus bounded, redacted metadata (`notifications/resources/updated uri=…`,
+`_meta.pi_summary` capped at 200 chars) — never raw params.
+
+Delivery per server: `inject_summary` (promotion only), `inject_and_run` (user message + one turn),
+or the default: evaluation against the dynamic rules by a sub-agent.
+
+## Tools
+
+After the handshake each server's `tools/list` is registered with pi:
+original names (prefixed with `<server>_` on collision), schemas passed through, `tools/call` text /
+image / resource content mapped to tool results, `isError` surfaced as a tool error, and
+`notifications/cancelled` sent when the user interrupts. `/triggers sources` lists the tools per
+server.
+
+## Processes
+
+An unattended run refuses a corpus of dangerous commands (see [loops.md](loops.md)); a project that
+legitimately needs one of those commands can list it:
+
+```toml
+[danger]
+allow = ["rm -rf /var/cache/mybuild"]
+```
+
+An entry means that command and nothing else. `rm -rf /var/cache/mybuild/tmp` is covered — a path
+strictly inside the one the entry names — but `rm -rf /var/cache/mybuild /`,
+`rm -rf /var/cache/mybuild/../..` and `rm -rf /var/cache/mybuild; rm -rf /` are not: they lose the
+exemption and are scanned like any other command. The commands reaching this gate are written by a
+model that may have read something hostile, so an entry has to mean one command and not a foothold;
+a run that needs two shapes of a command lists both.
+
+A sub-agent shares this process's live clients rather than opening its own, so a browser tab or
+database session opened in the chat is the one the loop sees. When a run's project is not this
+process's own, that project's `.pi/mcp.toml` servers are connected on demand and lent to the run
+(only if the user has trusted that project), so a loop is not at the mercy of which window owns
+the clock; the headless host does the same. Notifications are consumed by interactive processes only; a
+sub-agent ignores what its own connection pushes: sub-agents register no notification
+hooks. A push that injects into the chat (`inject_summary` / `inject_and_run`) reaches every window
+that has the server; a push evaluated against dynamic rules is
+evaluated once per project, by the pi that owns that project's checks.
+
+A repeated `[[server]]` name replaces the earlier entry (a diagnostic says so); the project file is
+`<project>/.pi/mcp.toml`.
+A machine-wide dedup window (`~/.pi/agent/loops/dedup.json`, 5 minutes) makes each push count once
+no matter how many pi windows are open, and results are promoted only into a chat that belongs to
+the rule's project (otherwise they go to the inbox). Crashed stdio servers are reconnected with
+exponential backoff, 20 attempts by default, each distinct error reported once (rather than marking them
+disconnected). `/triggers sources` lists MCP servers first, then the cron hook, then the dynamic
+checker, in registration order; a stdio server's last stderr line is shown as `stderr:`
+(diagnostic only — a successful push clears `last error`, stderr never sets it).
+`examples/mcp-notify-server.mjs` is a dependency-free push server to try this with.

package/docs/session-archive.md

@@ -0,0 +1,64 @@
+# Session archives
+
+pi's built-in `/export` and `/import` move the conversation. Neither moves the
+conversation **and** its automation. pi-loops provides that as `/session-export` and
+`/session-import` (pi already owns `/session`), as a `.pisession` archive — the transcript, the automation, and the loop state:
+
+```text
+pi-session-<first 16 chars of the id>.pisession   uncompressed ustar, mode 0600, never overwrites
+  manifest.json                  schema, timestamps, pi / pi-loops versions, source, sha256 of session.jsonl, sensitivity flags
+  session.jsonl                  pi's session file, verbatim
+  sidecars/cron.json             this project's cron jobs           (optional; dropped by --exclude-triggers)
+  sidecars/triggers.json         this project's trigger rules       (optional; dropped by --exclude-triggers)
+  loops/<job-id>.md              loop state per stateful job        (optional; follows the jobs)
+```
+
+```text
+/session-export [path] [--exclude-triggers]
+/session-import <path> [--activate-triggers=on|off] [--cwd <dir>] [--resume]
+```
+
+Both commands print a sensitivity warning before doing anything, success or failure.
+Import writes a new session file (fresh id, target cwd, `importedFrom` provenance in the header,
+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>`.
+
+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
+are rolled back if one fails, so a rejected archive leaves nothing behind (staged first, then committed). Archives contain the full transcript and tool history; treat them as sensitive.
+They never contain credentials, MCP config or the inbox. Note that pi writes a session file only
+after the first message, so an empty session has nothing to export.
+
+## /session-share — the transcript as a gist
+
+`/session-share` renders the transcript to Markdown and runs `gh gist create`, borrowing the GitHub
+CLI's credentials so nothing here ever has to hold one of yours:
+
+```text
+/session-share            secret gist (unlisted; anyone with the link can read it)
+/session-share --public   public gist
+```
+
+pi has a built-in `/share` of its own, and it is not the same thing. It exports the raw session
+JSONL and offers it to a hosted gateway first, falling back to a private gist, with no redaction
+and nothing shown to you beforehand. This command renders the transcript as Markdown, runs it
+through the redactor, writes a local copy, tells you what is in it, and only then asks — and it
+only ever talks to `gh`.
+
+Everything goes through the same redactor the rest of pi-loops uses (`src/redact.ts`), and the
+command shows what it is about to publish — messages, tool results, size, how many secrets it
+masked, and the path of the local copy in `<loops dir>/shares/` — then asks. Declining leaves the
+rendered file on disk and uploads nothing. `gh` must be installed and logged in (`gh auth login`);
+the gist is created by your account, and `gh gist delete <id>` removes it.
+
+The redactor is a net, not a guarantee. It knows the common shapes — provider keys, bearer tokens,
+JWTs, PEM blocks, `NAME=value` and `name: value` pairs whose name mentions a token, secret,
+password or key — and it does not know your employer's key format. A secret wrapped across two
+lines of tool output is two strings as far as it is concerned, and neither half matches. A
+transcript contains every file the agent read and every command it ran, so "0 secrets masked"
+means nothing matched, not that there is nothing in there. Read the local copy first — that is why
+the command writes one before asking.