@alphacoder-v0/pi-loops 0.22.8 → 0.24.0

package/docs/triggers.md

@@ -11,27 +11,80 @@ A rule is a natural-language **condition** and **action**:
 
 `/new-trigger` asks the agent to extract condition and action and call the `new_trigger` tool
 (the agent may also do this from ordinary chat). Rules **fire once** by default (`fire_once=false`
-for repeating), and their output stays in the TUI and audit unless `promote_to_chat` is set.
+for repeating). A matched rule's result is a finding in the inbox and a row in the page's loop
+activity strip, whatever `promote_to_chat` says; `promote_to_chat` also puts it in the conversation,
+and it is still one finding. The finding is news whatever the result says: it comes from outside, so
+a `· waits:` in it does not make it a decision. Its card and its strip row lead with what the check
+said after the `matched <rule-id>` it starts with; the finding keeps the whole text. A check whose
+result says exactly what the latest new finding of the same rule and project says files nothing
+more. The check records on its result's audit row whether it filed the finding or skipped it as a
+repeat; when the promotion falls back to the inbox, or its row dies, nothing more is filed for that
+check. A result that no check decided, such as a push with no rule, is filed once by its trace id.
 Time-based requests ("every hour", "daily", "定时任务") are refused and routed to `cron_create`.
 
 Tools: `new_trigger` (condition, action, spec, fire_once, promote_to_chat), `list_triggers`,
-`remove_trigger` (id | all), `set_trigger_state`. Creating, removing and re-enabling ask the user to
+`remove_trigger` (id | all), `set_trigger_state`. Removing and re-enabling ask the user to
 confirm, with `ctx.ui.confirm`.
 
+With a person present, in their own turn, `new_trigger` asks one question before it creates
+anything, with pi's `ctx.ui.select`: a terminal shows pi's selector, and the browser page draws the
+same question as a card. Its answers are Result, `promote_to_chat` (*Show it in this conversation*,
+the default, or *Put it in my inbox*), and Repeats, `fire_once` (*Once, then turn itself off*, the
+default, or *Every time it happens*). The tool returns `created dynamic trigger …` or
+`cancelled: …` in the same call; Cancel, Esc, an abort and thirty minutes with no answer write
+nothing. The page's **Watch for…** box sends one sentence as the chat message
+`Watch for: <sentence>`; a sentence with no time and nothing to wait for is answered by the page
+itself ("this reads like something to do now") and reaches no model. A sub-agent and a scheduled
+turn ask nobody: a scheduled turn in an open window asks the window guard's confirm, and a
+sub-agent is refused. See `docs/design.md`, decision 24.
+
 The model-facing tools see the calling project only: `list_triggers` takes `all_projects: true`
 when the user asks about the rest, and `remove_trigger { all: true }` clears this project's rules,
 never the machine's.
 
+### Rules that wait for a path
+
+A condition that is only "a path exists or appears" is recorded as pre-checkable when the rule is
+created (`precheck` on the rule in `triggers.json`: the condition it was read from, the path as
+typed, and the absolute path). The path is one token: `~/…`, `$HOME/…`, `${HOME}/…`, an absolute
+path, `./…` or `../…`, a relative path with a `/`, a file name with an extension (`build.done`), or a
+quoted path that may hold spaces. The verb is one of `exists`, `appears`, `is created`, `shows up`,
+`is there`, `is present`, `存在`, `出现`, `被创建`, `生成` (a `文件` or `目录` before the verb is the
+noun only when a space sets it apart from the path: `~/备份文件 存在` waits for `~/备份文件`), with an optional leading `when`, `if`,
+`once`, `当`, `如果` or `一旦` and an optional trailing `的时候`, `时` or `后`. `~` and `$HOME` are
+resolved in the process that creates the rule, so they are your home even when pi-loops in the
+background was started with another one; a relative path is resolved against the rule's project.
+
+Anything else is refused as path-only and checked by the model, as before: a glob, a second clause
+(`~/x appears and it contains ERROR`, `~/a exists or ~/b exists`), another verb, a bare word with no
+`/` or extension (`README`), a variable other than `$HOME`, `~user`, a URL, or a network path
+(`//server/…`, `/net/…`, `/Network/…`). A rule created before
+0.24.0 has no `precheck` and keeps calling the model; create it again to get the pre-check. So does
+a rule whose condition was edited by hand after it was created. An imported rule, from 0.22 or later,
+is read again when it is imported, against the project it is imported into and this machine's home,
+so a path-only one gets the pre-check then.
+
 ## Evaluation
 
-While at least one enabled rule exists, every `poll_interval_secs` (default 600; `--trigger-poll-secs`
-or `config.toml`) one sub-agent per project that has rules is started — by a pi open in that project
-(the session that created the rules if it is open, otherwise the lowest pid there), or by the
-machine leader when no pi is open in the project. The check receives the
+While at least one enabled rule exists, every `[triggers] poll_interval_secs` in `config.toml`
+(default 600; pi-loops re-reads it every minute) one check per project that has rules is run by pi-loops. The check receives the
 event JSON and every enabled rule and is told to inspect the filesystem, commands, clock or network
 as needed, execute the actions of matching rules, and reply `matched dyn-…` or exactly
 `no dynamic trigger rule matched`. Matched fire-once rules are disabled with `fired_at`.
 
+A rule that waits for a path (`precheck`, above) is looked at first: after the poll is claimed,
+pi-loops `stat`s the path, which follows symlinks, and gives up after 2 seconds. At most two looks
+are out at once in the process, and one per path; past that a look counts as one that cannot answer. While the path is
+absent the rule is left out of the check, so a project whose only rules wait for absent paths
+makes no model call and writes no `running` row. The audit gets one `trigger` row `waiting`
+("no model call until ~/build.done exists") at the first look pi-loops makes and whenever the path
+goes away, and one `appeared` when it is back; the check that follows names the rules the look let
+through in `details.prechecked` on its `running` row. When the look cannot answer (no permission, a
+mount that does not answer in time) the model checks the rule, as before. A repeating rule is
+checked every poll while its path exists, and matches again after the path is deleted and comes
+back. The rule's row on the page says what it waits for and when the next look is: "waits for
+~/build.done · next look 09:22 · no model call until the file exists".
+
 Pushed MCP notifications (see [mcp.md](mcp.md)) enter the same runtime and are evaluated against
 the rules unless the server is configured as an `inject_summary` / `inject_and_run` feed.
 
@@ -41,7 +94,9 @@ job backoff, same numbers — literally the same function, `backoffWaitMs` in `s
 The count lives on the rule (`consecutive_failures`,
 `last_check_failed_at`), a check that completes clears it — including `/triggers run <id>`, which is
 the way to retry a backed-off rule now — and entering the backoff is audited as `backoff` with the
-rule ids and the failure count. Pushes are unaffected: an event is worth one attempt.
+rule ids and the failure count. Pushes are unaffected: an event is worth one attempt. While a rule
+is in that state `/triggers rules` marks it `[failing ×N]` after its state bracket; a disabled rule
+is not polled and is not marked.
 
 ## What happens when the machine is busy or over budget
 
@@ -66,10 +121,26 @@ on what was refused:
 
 ## Promotion and audit
 
-A matched rule with `promote_to_chat` inserts `[Trigger <trace>] <result>` into the chat context
-of the pi that ran the check (visible to future turns; no model call when idle, a follow-up turn
-when the agent was busy). Because checks run in the rule's project, that is the right chat; only
-when no pi is open there does the result go to the inbox (`redirected`). One check evaluates every
+A matched rule with `promote_to_chat` is a request addressed to a conversation: the one that
+created the rule while a window holds it; else the conversation a window holds in the rule's project
+(lowest pid first, as 0.22.8 chose its owner), so the result reaches the chat you are working in;
+else the closed creating conversation. It is one row in `requests/<session>.jsonl`, which stays there until `[Trigger <trace>] <result>` is
+in the conversation. The window holding the conversation inserts it (visible to future turns; no
+model call when idle, a follow-up turn when busy: `promoted`, `to: "chat"` in the audit when it
+landed at once, `to: "queued"` when another process or a later drain delivers it). If no window
+holds the conversation, pi-loops appends the result to it, holding the conversation for that one
+write, so it is there when the conversation is resumed (`appended`); the rule's finding in the
+inbox is what the next session start's `[inbox] since you last looked` line counts. pi-loops appends it within moments of the row being
+written: pi-loops watches `requests/` and `leases/`, and a window that wrote the row rings it over
+the control socket; its 30-second tick is the floor under both, so a ring that is lost costs at most
+one tick, and never a row. If pi-loops cannot take the conversation at
+that instant (someone wrote it in the last two minutes), the row waits and pi-loops appends it on a
+later tick. A row whose delivery fails waits a minute, then five, and blocks nothing behind it; at
+the third failure, or when the conversation's file is gone, it is a dead letter: a finding in the
+inbox marked for the conversation, then a `request` audit row (`dead`), then the row is removed, in
+that order so a crash in between loses nothing. A rule's result has its finding already (every match is one), so its dead letter files no second one; any other row's finding reads `could not be delivered (<why>): <prompt>`. A rule with no
+creating conversation (made from a shell, imported, or made by a loop's run) sends results to the
+project's open window as above, and to the inbox (`redirected`, which finds the match's finding and adds nothing) when none is open. One check evaluates every
 rule of the project at once, so it runs under **one** model: the first rule that has one recorded
 (`/triggers set <id> --model … | -`), and that rule's thinking level with it — a thinking level
 belongs to the model it was chosen for, and a rule with a model but no level falls back to the
@@ -78,22 +149,41 @@ the longest of the project's rules (`--timeout`), else `[triggers] run_timeout_s
 session entries (`trigger`, `trigger_result`, `trigger_promotion`); `/triggers audit [N] [--all]`
 shows this project's rows with decisions and transcript paths. The complete set of states:
 
-- admission — `accepted`, `deduped`, `deferred` (no slot, or handed to the pi that owns the rules),
-  `taken_over` (the owner did not claim it), `dropped` (the held list was full), `budget_exceeded`,
-  `cycle_suppressed` (it reached a sub-agent), `backoff`, `disabled` (the rule's project is gone);
+- admission — `accepted`, `deduped`, `deferred` (no slot), `dropped` (the held list was full),
+  `budget_exceeded`,
+  `cycle_suppressed` (it reached a sub-agent), `backoff`, `disabled` (the rule's project is gone),
+  `waiting` (a rule's path is absent: no model call until it exists) and `appeared` (it is back);
 - the run — `running`, then `completed` / `failed` / `aborted`, or `no_rules`;
-- promotion — `promoted`, `redirected` (to the inbox: no pi open in that project), `skipped` (no
-  matched rule has `promote_to_chat`).
-
-Rows of type `cron_control_plane` use the operation as the state instead: `add`, `enable`,
-`disable`, `remove`.
+- promotion — `promoted` (into this chat, or queued for the conversation), `appended` (pi-loops wrote
+  a queued result into the closed conversation), `redirected` (to the inbox: no window is open in the rule's project, and the rule has no
+  conversation or its conversation's file is unknown or gone; or a pi-loops 0.22 window has it open), `skipped` (no matched rule has `promote_to_chat`).
+
+Rows of type `request` record what became of a row in `requests/<session>.jsonl` that did not end
+in the conversation: `failed` (one delivery failed, pi refused the hand-over, or pi dropped it
+unwritten; the row waits out a backoff, or is offered again), `dead` (three failures, or the
+conversation's file is gone: it is a finding in the inbox now; never a person's message), `cancelled`,
+`done` (a stop or cancel that acted: the turn aborted, or the queued row taken out), `stale` (a stop
+or cancel with nothing to act on, a goal row without a goal, or a person's message whose
+conversation is gone), `job-removed`, `refused` (the row's
+`mode` is not the one its source gets, so a line edited in the file, or written by another version,
+cannot widen what a turn may do; the row never runs). Two more come from the inbox in the browser
+page: `claimed` (a finding's claim was queued for the conversation that created its loop; the row
+is the `inbox:<id>` one `/inbox claim` writes, and the trace id is its id) and `dismissed` (a
+finding was dismissed from the page; the trace id is the finding's, and `details.reason` is what the
+person gave, redacted, or null).
+
+Rows of type `cron_control_plane` use the operation as the state instead: `add`, `set` (a
+schedule changed in place by `/cron set --schedule` or by a suggestion applied from the page, with
+`details.before_schedule` and `details.after_schedule`; an edit that leaves the schedule alone
+writes none), `enable`, `disable`, `remove`. The page's and `/cron set`'s rows are in
+`triggers-audit.jsonl` (source `page` or `slash`); the others are also session entries.
 
 A 5-minute dedup window collapses repeated events with the same idempotency key (per project for
 rule evaluation, per window for injected pushes).
 
 ```text
-/triggers status      rule counts, checker ownership, last check, push sources
-/triggers rules       this project's rules  (--all for every project)
+/triggers             this project's rules; the same as /triggers rules  (--all for every project)
+/triggers status      rule counts, what checks them, the last check, push sources
 /triggers sources     local checker + each MCP server: state, queued/dropped/deduped, tools
                       (/triggers hooks is the same view)
 /triggers enable <id> /triggers disable <id> /triggers remove <id>   also --all | --all-projects
@@ -106,7 +196,10 @@ rule evaluation, per window for injected pushes).
 ```
 
 Cron runs share this runtime's views: they appear in `/triggers running` and `/triggers audit`
-and can be aborted by run id.
+and can be aborted by run id. A plain job's turn running in a closed conversation in the background
+is stopped through a request (`stop` in `requests/<session>.jsonl`), which that process reads within
+a tick whether or not its socket answers: `/triggers abort <run-id>` says `requested stop for
+<run-id> (session <id>)`. Loop runs and checks, and `--all`, are asked of it over the socket as before.
 
 `/triggers run <id>` takes the same path a periodic check takes — dedup, audit, the check
 sub-agent, promotion — and skips only the poll ledger, which is what running it now means. The
@@ -118,8 +211,9 @@ Cycles are bounded by a hop count: sub-agents run at hop 1 and still have the
 cron/trigger tools, so a trigger action can schedule a job; they never run the trigger runtime, so
 nothing nests. Prompt-class operations — creating or removing a trigger,
 re-enabling a trigger or a cron job — are denied fail-closed in sub-agents (no control-plane
-prompt channel there); `cron_create` and `cron_remove` work and the control-plane audit records
-`actor: sub-agent`. Sub-agents never handle triggers themselves: they ignore MCP pushes, and the
+prompt channel there). `cron_create` works there, and so does disabling a job of the sub-agent's own
+project; the control-plane audit records `actor: sub-agent`. `cron_remove`, re-enabling a job and
+touching another project's job are denied there like the other prompt-class operations. Sub-agents never handle triggers themselves: they ignore MCP pushes, and the
 runtime audits anything reaching hop ≥ 1 as `cycle_suppressed` (hops are counted per trace, but the
 bound that matters is structural: a sub-agent session never acts on a trigger at all).
 
@@ -127,8 +221,8 @@ bound that matters is structural: a sub-agent session never acts on a trigger at
 
 `/triggers enable|disable <id>` prints the rule's state, condition and action (and the
 fire-once note); `/triggers sources` lists MCP servers, the cron hook and the dynamic
-checker in registration order with a `sources: N total, M connected, K require
-attention` summary in `/triggers status`. Errors are worded once and kept that way (`unknown /triggers command:
+checker in registration order with a `Sources: N, M connected, K need attention` summary in
+`/triggers status` (the last part only when K is not 0). Errors are worded once and kept that way (`unknown /triggers command:
 …`, `usage: /triggers remove <id>|--all`, `/new-trigger` parse messages). `/triggers remove --all`
 clears this project's rules; `--all-projects` is the explicit machine-wide sweep.
 

package/docs/troubleshooting.md

@@ -1,14 +1,23 @@
 # Troubleshooting
 
-**Nothing fires.** `/cron scheduler`: is this process the timer owner or standby? If the owner died
-without cleanup, a standby takes over within 90 seconds. A job shows `next …` when it will run
-*here*. A plain job marked `[session <id> — resume it to run]` belongs to another session and fires
-only there (`--resume` it, or `/cron add` it again in this chat); a loop marked
+**Nothing fires.** `/pi-loops status` shows whether pi-loops is running. If it cannot start, the window
+shows `loops paused: pi-loops could not start`; `/pi-loops status` gives the reason and log path. A job shows
+`next …` when it will run somewhere: here, in another window, or in the background. `paused: <why>` means
+pi-loops will not run it; `/pi-loops status` says why. A plain job marked `[session <id> — resume it to run]`
+belongs to a conversation whose file pi-loops never saw (`--resume` it once, or `/cron add` it again
+in this chat); a loop marked
 `[orphan: cwd missing]` was disabled because its checkout is gone.
 
 **A run failed.** `/cron runs` shows the error; `/cron trace <job> 1` shows the sub-agent's
-transcript; `pi --session <file>` resumes it. Sub-agents run inside your interactive pi with its
-credentials, tools and MCP servers; they cannot answer permission prompts (use `--tools` to restrict).
+transcript; `pi --session <file>` resumes it. Loop runs and rule checks run in the background. They
+use the credentials pi saved, the built-in tools of the chat the loop was made in (or the job's
+`--tools`), the MCP servers in `mcp.toml`, and the project's own servers and settings only when pi
+has saved trust for that exact directory (`/trust` in a pi opened there). A plain job's run in its
+closed conversation uses pi's saved trust for that directory or a parent of it. They do not get `-e` extensions or flags from your pi
+window, and they cannot answer permission prompts. The background process has the environment of
+the process that started it: a pi window's, whose shell's exported keys it then has, or a service
+manager's, which has none of them. `pi-loops status` names that process; `pi-loops restart` from a
+shell gives it that shell's environment. Keys saved with pi's `/login` always reach it.
 
 **Findings never arrive.** The loop must end its reply with `<inbox>…</inbox>` tags; check
 `/cron trace`. Quiet runs are normal. With `--verify`, dropped findings and reasons are on the run
@@ -39,7 +48,7 @@ digits into the box on that page. The terminal that started the session printed
 
 **The phone cannot reach it at all.** The server binds loopback by default, and a phone has no
 route to that. Either `tailscale serve --bg 4173` (the server stays on loopback; the tailnet does
-TLS) or start with `pi-loops --host 0.0.0.0` for a phone on the same wifi. See
+TLS) or set `[page] host = "0.0.0.0"` in `config.toml` and run `pi-loops restart` for a phone on the same wifi. See
 [cli.md](cli.md#from-a-phone).
 
 **The QR is offered but scanning it goes nowhere.** The QR encodes the address *the browser you
@@ -48,20 +57,21 @@ address a phone could use — it says so instead of drawing one. Open the tailne
 the desktop first, then press it there. Where the machine has several addresses, the dialog lists
 them with the interface each belongs to; a docker or libvirt bridge is not the one.
 
-**"port 4173 is already in use" — or a second `pi-loops` opened the first one's window.** Starting
-a second session while one is up hands you the window that is already there rather than failing.
-That is deliberate. `--port <n>` starts a genuinely separate one, and the browser stays signed in:
-the token is the one file both of them read, and a cookie is not scoped to a port — `localhost:4173`
-and `localhost:4180` are the same site to a browser, which is the fact the `Sec-Fetch-Site` check
-here is built around. A `--port` that is not a number is refused rather than quietly served on 4173.
+**"an older pi-loops page is still open on 127.0.0.1:4173" or "is used by another program".** The
+page is served by pi-loops in the background, and a second `pi-loops` opens a conversation in it
+rather than starting a second page. Before 0.24 the page ran in its terminal: quit that one (Ctrl-C
+in its terminal) and the page takes the port within 30 seconds. Another program on 4173 is not
+waited for: set `[page] port` in `config.toml`, then `pi-loops restart`. A browser pairs again on the
+new port: the secret it keeps belongs to the old address, port included. Run `pi-loops` and it opens
+a window that is signed in.
 
 **A pairing code stopped working.** They last ten minutes, are good for one use, and closing the
 dialog retires the one it was showing. Twenty wrong guesses disable pairing until another code is
 made. Press **add device** again.
 
 **Every device was signed out at once.** Something removed `~/.pi/agent/loops/web-token`, or
-`PI_LOOPS_DIR` points somewhere new — the token is that file, and the cookie every device holds is
-its contents.
+`PI_LOOPS_DIR` points somewhere new — the token is that file, and every paired device is recorded
+against it in `web-devices.json`.
 
 **The window stops answering — you type, your message appears, no reply ever does.** The event
 stream is numbered per run of the server process, so a page that was open across a restart can end
@@ -79,7 +89,9 @@ Bearer tokens come from `$TOKEN_REF` or pi's credential store; endpoints must be
 127.0.0.1. Custom notifications without `_meta.pi_dedup_key` are dropped and counted.
 
 **Hooks do not run.** Startup warnings list malformed rules. Project hooks need
-`allow_project_hooks = true`. Hooks fire only in the interactive pi, not in sub-agents.
+`allow_project_hooks = true`. `agent_*`, `turn_*`, `message_*`, `tool_*` and `compaction` fire in the pi you are talking to.
+`run_start` / `run_end` fire only in pi-loops in the background, for loop runs (output in
+`host.log`); a plain job fires neither. Sub-agents fire nothing. See [hooks.md](hooks.md).
 
 **`/session-export` says the session is ephemeral.** pi writes the session file after the first
 message; `--no-session` sessions cannot be exported.
@@ -93,17 +105,16 @@ run is recorded as aborted rather than failed, so the slot is still owed and the
 streak is untouched; it simply will not be dispatched again until the day rolls over or the cap is
 raised.
 
-**`pi-loops host status` says the host "is not answering" but it is running.** Before 0.4.0 this
+**`pi-loops status` says pi-loops "is not answering" but it is running.** Before 0.4.0 this
 happened whenever `PI_LOOPS_DIR` was deep: a unix socket path is capped at 108 bytes, so
-`<dir>/host.sock` failed to bind and the control channel silently did not exist. It now falls back
-to a short path under a per-user directory in the temp directory. If you still see it, the host is
-genuinely wedged — `host.log` has its last line, and `pi-loops host stop` escalates to SIGTERM.
-
-**A host is running that you did not start.** That is the design: the last interactive pi to quit
-hands the clock to a headless host when there is work for it (an enabled loop or rule for this
-machine, or an MCP server that pushes). `pi-loops host status` says what it is doing and what it
-has spent; `pi-loops host stop` ends it; `[host] auto = false` stops the hand-off happening at all.
-After testing with a throwaway `PI_LOOPS_DIR`, remember that the host it spawned outlives the pi
+the old socket path failed to bind and the control channel silently did not exist. It now falls back
+to a short path under a per-user directory in the temp directory. If you still see it, pi-loops is
+genuinely wedged — `host.log` has its last line, and `pi-loops stop` escalates to SIGTERM.
+
+**pi-loops is running and you did not start it.** A window starts pi-loops when there is work to run, and
+`pi-loops status` shows its state; `pi-loops stop`
+stops it until `pi-loops start`, or until `pi-loops` opens the page. `[host] auto = false` prevents windows from starting it.
+After testing with a throwaway `PI_LOOPS_DIR`, remember that pi-loops it started outlives the pi
 that spawned it — it is polling and billing against *that* directory until stopped.
 
 **The browser front end refuses a slash command.** It drives `pi --mode rpc`,