@dumbmice/pi-todo-loop 0.2.1 → 0.3.1

package/AGENTS.md

@@ -102,14 +102,17 @@ adding a `CHANGELOG.md` line — all in the same commit.
 - **Only a settle spends a round.** `turn_end` fires for every assistant response, including one that
   ended in a tool call; those already cause pi's next request, so the hook returns before deciding. A
   round, a marker and a stall are therefore always about a turn that would have ended the run.
-- **A tool turn clears the stall and spends no round** — except a tool turn that ends `error`/`aborted`,
-  which records the stop and leaves the counter alone. Tool turns already cause pi's next request, so
-  they must not consume a round; but they are work, so they reset `stalled` and re-arm the block hint.
-- **Nothing stops the loop for being quiet.** There is no strike limit: `stalled` decides only when the
-  nudge offers `todo_loop_block`, once per stall, and tool work re-arms it. A blocked agent and a lazy
+- **A tool turn spends no round and resets `settleRun`, whatever its outcome** — an errored or aborted
+  one also records the stop. Tool turns already cause pi's next request, so they must not consume a
+  round; because they are work, the stop right after one is not asked about, and the stop after that is.
+- **Nothing stops the loop for being quiet.** There is no strike limit: `settleRun === 2` decides when
+  the nudge names `todo_loop_block` — the second consecutive stop with no work between them and no list
+  change, once per run of settles, the one shape the question answers. A blocked agent and a lazy
   one are indistinguishable from here, so the agent is asked rather than judged; the only stops are a
-  clear list, the round cap, an error, and the human's own `todo_loop_block` call.
-- **A stop keeps the counters; only a new human message resets them.** Clearing `rounds` / `stalled` on
+  clear list, a configured round cap, an error, the agent's `todo_loop_block`, and your own pause or
+  kill switch. There is no cap by default, so a stall that never resolves warns every tenth settle
+  instead of ending the run.
+- **A stop keeps the counters; only a new human message resets them.** Clearing `rounds` / `staleSettles` on
   stop re-arms a full budget on the next `turn_end` under the same anchor (another extension's
   continuation, a provider retry). The anchor comparison is the only *automatic* reset;
   `/todoloop reset` and process start clear the counters explicitly. A queued human message is a
@@ -144,10 +147,11 @@ introduces an edge.
 |---|---|
 | continues only while items are open | `continues while work is open and the turn did work`, `stops when the list is clear`, `stops when there is no list at all` |
 | error and aborted outcomes never continue | `never continues on an error or aborted turn` |
-| a no-progress settle never stops the loop; the block hint is offered once per stall | `a no-progress settle continues, and offers the block hint once` |
+| the hint asks on the second consecutive stop, once per run of settles | `the hint asks exactly one stop after the last one`, `state machine: the block clause asks on the second consecutive stop, and once per run` |
+| a tool turn restarts the hint run, so a tool-heavy stall is still asked | `state machine: a tool turn restarts the clause run, so a tool-heavy stall is still asked` |
 | the first sighting of a list is progress, not a stall | `the first sighting of a list counts as progress, not a stall` |
-| a list change clears the stall and re-arms the hint | `a list change clears the stall and re-arms the hint` |
-| the round cap stops the loop | `round cap stops the loop`, `config caps are honoured` |
+| a list change is progress, so it is never asked about | `a list change is progress, so it is not asked about` |
+| no cap by default; a configured cap stops the loop | `no round cap by default`, `a configured round cap stops the loop`, `config caps are honoured` |
 | a new human message resets the budget | `a new human message resets the budget` |
 | a stop keeps the counters for the anchor, and a new message clears them | `a stop keeps the counters, so a cap stays shut for the same anchor`, `a new human message after a stop starts a fresh budget`, `the round cap is sticky for one human message` |
 | the newest custom entry wins over older ones | `reads the newest rpiv-todo custom entry` |
@@ -165,8 +169,8 @@ introduces an edge.
 | a malformed context payload is not rewritten | `context leaves a malformed payload alone instead of rewriting it` |
 | either kill switch disables both hooks | `the global kill switch disables both hooks`, `the project-local kill switch disables both hooks` |
 | only a settle spends a round: tool turns cost nothing | `a turn that ran tools spends no round and appends no marker` |
-| a tool turn clears the stall and re-arms the hint | `tool turns clear the stall but never spend a round` |
-| the block hint is offered once per stall, on the repeat stop | `the nudge offers todo_loop_block once, after a repeat stop` |
+| a tool turn restarts the hint run, so a tool-heavy stall is still asked | `tool turns spend no round, clear the stall, and restart the hint's run` |
+| only the first nudge that did not move the list names the block tool | `only the first nudge that did not move the list names todo_loop_block` |
 | `todo_loop_block` stops the loop and reports the reason | `todo_loop_block stops the loop for this message and reports the reason` |
 | a block without a reason is refused | `a block without a reason is refused and does not stop the loop` |
 | the human's next message clears the block | `the human's next message clears the block` |
@@ -177,7 +181,11 @@ introduces an edge.
 | the kill switch silences the block tool too | `the kill switch also silences todo_loop_block` |
 | the block tool declares a prompt snippet and a self-naming guideline, so pi lists it in `<tools>`/`<rules>` | `the block tool declares a prompt snippet and a self-naming guideline` |
 | a paused loop refuses the block tool and stays silent | `a paused loop refuses todo_loop_block and stays silent` |
-| a stall clause that lands on the cap round is reported, not dropped | `state machine: cap stays shut across a repeated settle under the same message`, `a stale list stops on the cap with a reason that says so` |
+| an uncapped runaway warns every tenth no-progress settle | `an uncapped runaway warns every tenth settle that changes nothing` |
+| the warning counts replies since the list changed, not replies in a row | `the warning counts replies since the list changed, not replies in a row` |
+| emptying the list by deleting tasks warns; by completing them does not | `a list emptied by deleting its tasks is announced`, `a list emptied by ticking finished tasks is silent`, `an older tombstone does not make a completion look like a deletion` |
+| clearing the list with `clear` is announced, since nothing was completed | `a turn that clears the list with the todo clear action is announced` |
+| a stall clause that lands on the cap round is reported, not dropped | `a cap that lands on the bare stall names it in the reason` |
 | the next human message clears the block and the stale `last:` | `the human's next message clears the block` |
 | a continuation appends one hidden `custom_message` with a constant body and preserves prior proposals | `turn_end requests one turn with a hidden marker when work is open` |
 | a malformed event payload does not throw | `turn_end tolerates a malformed event payload instead of throwing` |
@@ -203,7 +211,7 @@ introduces an edge.
 3. Add cases to `test/loop.test.ts`: the new rule, its boundary, and the ordering against the reset
    and cap rules. Order matters — the anchor reset runs before every other check.
 4. Add a user-visible line to the `/todoloop` status if an operator needs to see it.
-5. Update the README *Behaviour to expect* list and `CHANGELOG.md` under `[Unreleased]`.
+5. Update the README *What it looks like* section and `CHANGELOG.md` under `[Unreleased]`.
 
 ## Fragile areas
 
@@ -212,7 +220,7 @@ Ranked by how easily a small change breaks them.
 1. **Two different tails.** A continuation whose *persisted projection* ends on an assistant message is
    rejected by pi (`canContinue`); the *request* has no such constraint but must keep role alternation.
    Conflating the two produced the round-2 marker leak. `test/index.test.ts` pins both shapes.
-2. **Counter lifecycle.** `rounds`, `stalled` and `anchor` are mutated in one place and reset in three
+2. **Counter lifecycle.** `rounds`, `staleSettles`, `settleRun` and `anchor` are mutated in one place and reset in three
    (anchor change, `/todoloop reset`, process start). A missing reset either loops forever or refuses to
    continue after one bad turn; a reset in the wrong place (inside `stop()`) silently re-arms the cap.
 3. **The anchor.** It must be human-authored and never empty. `#<index>` is the fallback when an entry
@@ -290,7 +298,7 @@ projects, or tightening `canContinue`; the second is how pi renders a custom too
 prompt, since the harness stub never builds one — a tool without a `promptSnippet` was silently dropped
 from `<tools>` in pi 1.5.0. Drafts are committed before the continuation is validated, so that change
 would persist a marker, drop the continuation, and leave `/todoloop` reporting `continuing: round n/12`
-until it reports `round cap` with zero continuations — while every test here stays green, because the
+until it reports a cap stop (`stopped: N continuations used, …`) with zero continuations (with the default there is no cap, so the symptom is a rising `continuing: round n` that never stops) — while every test here stays green, because the
 harness drives a stub `pi`.
 
 Before every version bump, on the *new* pi, run the documented live check once:
@@ -318,7 +326,7 @@ the request).
   the final actionable boundary that can append entries and request one continuation, and at
   `turn_end` the hook has to reconstruct "the run would otherwise end" from `toolResults.length === 0`.
   The consequence is a bounded wasted round when a human message is queued mid-turn, and the stall
-  reset lives in the adapter rather than in `decide()`. Moving the decision is the 0.2.0 change; it must
+  reset lives in the adapter rather than in `decide()`. Moving the decision is the next major change; it must
   ship with a CHANGELOG line because it changes which turns spend a round.
 - **`getBranch()` is not the model-visible context** (register item 16): after compaction the panel can
   show work the model has no list for.
@@ -369,7 +377,7 @@ Cutting a release:
 ```bash
 npm version patch --no-git-tag-version    # or minor/major; the tree must be clean
 VERSION="$(node -p "require('./package.json').version")"
-# move the CHANGELOG entry from [Unreleased] to "## [$VERSION] — YYYY-MM-DD"
+# move the CHANGELOG entry from [Unreleased] to "## [$VERSION] - YYYY-MM-DD"
 git add -A
 git commit -m "chore: release v$VERSION"
 git tag -a "v$VERSION" -m "v$VERSION"

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-11-10
+
+### Changed
+
+- Verified against **pi 1.5.1**: `PI_API_SNAPSHOT` and the tested-version table move with it. Nothing in
+  the extension needed changing — 1.5.1's breaking changes touch `GrepOperations.readFile` callbacks and
+  the `tools: []` field for OpenAI-compatible endpoints, neither of which this package uses. A live
+  session on 1.5.1 created a list, wrote two files, closed both tasks and stopped with no nudges, and
+  the tool still renders in the prompt's `<tools>` and `<rules>` sections.
+
+## [0.3.0] - 2026-11-06
+
+### Added
+
+- A warning to the human every tenth reply that leaves the todo list unchanged, while the loop keeps
+  going: it names the count, the open tasks, and the two brakes (`/todoloop pause`, `maxRounds`). It is
+  keyed on `staleSettles`, which tool turns do not clear, so it also catches the model this package
+  exists for: tools running, list frozen. With a configured cap it says how many continuations remain.
+
+### Changed
+
+- **Breaking:** `maxRounds` defaults to `null`, so there is no continuation cap. The loop now ends when
+  the list clears, the agent calls `todo_loop_block`, an error or abort occurs, or you pause it. Set a
+  number to bound what one message of yours can cost; the value is still clamped to ≤ 1000, and a value
+  below 1 stays unlimited rather than falling back to a default.
+- The "list was cleared by todo alone" warning now counts *calls* rather than snapshot rows: it fires
+  when the turn that emptied the list deleted tasks, and names how many. Finishing work and closing
+  every task in one turn is the honest ending and no longer warns, and a tombstone from an earlier turn
+  is not news. A result with no `action` at all keeps the old, vaguer wording.
+- The user-facing text is plain English now: `/todoloop` says `asked to continue: 3 (no limit)`,
+  `replies since the todo list last changed: 0`, `tasks open: 2 of 5`,
+  `counting from: your message … — a new message restarts the count`; reasons read
+  `continuing: 2 tasks still open, continue 3`, and a cap reads
+  `stopped: 12 continuations used, 3 tasks still open`. The words "settles", "stalled", "round cap"
+  and "hard bound" are gone from `/todoloop`, the stop reasons and the warnings.
+- The `todo_loop_block` clause now rides only on the bare stall: the model stopped, got one nudge, and
+  stopped again without running a tool and without the list changing (`settleRun === 2`). A stop that
+  follows real work gets the plain nudge; the stop after it is asked, so a tool-heavy run with a frozen
+  list is still asked. One request per stall, never repeated. `hintSent` is gone with it.
+
+### Upgrade notes
+
+- A session that relied on the old default of 12 now runs unbounded. An explicit `"maxRounds": 12` in
+  the config file is honoured exactly as before, so that is the one-line way to keep the old ceiling.
+- `"maxRounds": 0` used to mean "use 12"; it now means unlimited, like any value below 1.
+
 ## [0.2.1] - 2026-11-05
 
 ### Changed
@@ -143,4 +189,8 @@ Initial release.
 
 [0.1.0]: https://github.com/DumbMice/pi-todo-loop/releases/tag/v0.1.0
 [0.1.1]: https://github.com/DumbMice/pi-todo-loop/releases/tag/v0.1.1
-[Unreleased]: https://github.com/DumbMice/pi-todo-loop/compare/v0.1.1...HEAD
+[0.2.0]: https://github.com/DumbMice/pi-todo-loop/releases/tag/v0.2.0
+[0.2.1]: https://github.com/DumbMice/pi-todo-loop/releases/tag/v0.2.1
+[0.3.0]: https://github.com/DumbMice/pi-todo-loop/releases/tag/v0.3.0
+[0.3.1]: https://github.com/DumbMice/pi-todo-loop/releases/tag/v0.3.1
+[Unreleased]: https://github.com/DumbMice/pi-todo-loop/compare/v0.3.1...HEAD

package/README.md

@@ -52,7 +52,8 @@ It stops for one of these reasons, and `/todoloop` always says which:
 |---|---|
 | the list is clear | `stopped: list is clear` — the normal ending |
 | the model said it needs a person | `waiting for you: waiting on Dana's review` — it called `todo_loop_block`; your next message resumes |
-| the budget is spent | `stopped: round cap 12 reached, 3 open` — 12 continuations for your one message; if it ends with `the agent stalled and may need a person`, ask it what it is waiting on |
+| a configured cap is reached | `stopped: 12 continuations used, 3 tasks still open` — only when `maxRounds` is set; if it ends with `the agent may need you`, ask what it is waiting on |
+| it never had a list | `stopped: no list` — the model has not called the todo tool in this session |
 | the turn failed | `stopped: turn outcome was error` — the provider failed, or you aborted it |
 
 ## When it helps
@@ -60,25 +61,31 @@ It stops for one of these reasons, and `/todoloop` always says which:
 - Long, multi-step work where the agent summarises and hands back halfway.
 - Sessions long enough to be compacted — the list survives on disk; the nudge is what gets the model to
   read it again.
-- A model that runs tools but rarely updates its list. It will still be nudged; it may keep working to
-  the round cap.
+- A model that runs tools but rarely updates its list. It will still be nudged, and with no cap by
+  default it keeps going until the list clears.
 
 ## When it does not
 
 - **No todo tool installed.** The extension is inert: nothing continues.
-- **You want an autonomous agent that invents its own goals.** This drives the list you have; it stops
-  after 12 continuations per message by default.
+- **You want an autonomous agent that invents its own goals.** This drives the list you have; nothing
+  here adds work you did not ask for.
+- **You want a hard ceiling on cost.** There is no continuation cap by default — set `maxRounds` if you
+  want one, otherwise a model that keeps stopping will keep costing turns. `/todoloop` says `(no limit)`,
+  and every tenth reply that leaves the list unchanged raises a warning.
 - **You want the continuations visible.** They are silent by design.
-- **You want the agent to keep going after you said stop.** Your instruction wins; a model that reads
-  "stop" as final can say so with `todo_loop_block`, and that stops the loop immediately.
+- **You want your "stop" to be final.** Your instruction reaches the model, not the loop. A model that
+  reads "stop" as final can say so with `todo_loop_block`, and that ends it; otherwise the loop keeps
+  asking, so use `/todoloop pause` while you are away.
 
 It buys *liveness*, not work. A model can satisfy the loop by closing tasks, including deleting
-placeholders, and a list that is never updated looks the same as one that is finished. Clearing the list
-is the only thing that stops it, so the list has to mean something to you.
+placeholders, and a list that is never updated looks the same as one that is finished. What ends it is
+the list emptying, the agent asking for a person, a turn that fails, the `maxRounds` limit you set, or
+you pausing it — so the list has to mean something to you.
 
 The extension never edits your prompt. The only *variable* text it gives the model is a one-line nudge —
-*continue, and read or update the list with the todo tool* — plus one constant tool declaration and the
-prompt entry pi derives from it (`todo_loop_block`; neither carries task state), so the list stays the
+*continue, and read or update the list with the todo tool* — which adds one sentence offering
+`todo_loop_block` when the agent has stopped twice without doing anything. Plus one constant tool
+declaration and the prompt entry pi derives from it; neither carries task state. The list stays the
 agent's to maintain and the conversation stays yours.
 
 ## Configuration
@@ -87,13 +94,13 @@ Optional, at `~/.pi/agent/todo-loop.json`:
 
 ```json
 {
-  "maxRounds": 12
+  "maxRounds": null
 }
 ```
 
 | Key | Default | What it does |
 |---|---|---|
-| `maxRounds` | `12` | continuations allowed per message to the agent |
+| `maxRounds` | `null` | continuations allowed per message; `null` means no limit, a number caps it (clamped to 1000) |
 
 A missing or broken file falls back to these values; a bad config never fails a turn.
 
@@ -101,16 +108,16 @@ A missing or broken file falls back to these values; a bad config never fails a
 
 | Command | What it does |
 |---|---|
-| `/todoloop` | status: mode, rounds, stalls, open tasks, whether it waits for you, why it last stopped, config path |
+| `/todoloop` | status: mode, how often it has been asked to continue, replies since the todo list last changed, open tasks, whether it waits for you, why it last stopped, config path |
 | `/todoloop pause` | stop continuing until you resume or restart |
 | `/todoloop resume` | allow the next turn to continue again |
-| `/todoloop reset` | clear the counters, the list signature and any pending `todo_loop_block` |
+| `/todoloop reset` | restart the count for this message and forget any pending `todo_loop_block` |
 
 **Kill switch** — checked before every decision:
 
 ```bash
 touch ~/.pi/agent/todo-loop-off     # everywhere
-touch .pi/todo-loop-off             # this project only
+touch .pi/todo-loop-off             # this directory only
 ```
 
 ## Is it working?
@@ -119,11 +126,12 @@ After a response that made no tool calls while tasks are open, `/todoloop` shoul
 
 ```
 todo-loop active
-rounds 1/12 · stalled 0
-open 2/5 tracked
-anchor 4f3c1a2e
-last: continuing: round 1/12, 2 open
-config ~/.pi/agent/todo-loop.json
+asked to continue: 1 (no limit)
+replies since the todo list last changed: 0
+tasks open: 2 of 5
+counting from: your message 4f3c1a2e — a new message restarts the count
+last: continuing: 2 tasks still open, continue 1
+config /home/you/.pi/agent/todo-loop.json
 ```
 
 To count continuations in a session file:
@@ -136,12 +144,13 @@ grep -c 'todo-loop:continue' ~/.pi/agent/sessions/<project>/*.jsonl
 
 | Symptom | What to do |
 |---|---|
-| Nothing continues | Check `/todoloop`: `DISABLED` means a kill-switch file exists, `PAUSED` means you paused it. `last: stopped: no list` with `open 0/0 tracked` means the model has not created a list in this session; if the open count is non-zero the tool is writing a shape this extension does not read |
+| Nothing continues | Check `/todoloop`: `DISABLED` means a kill-switch file exists, `PAUSED` means you paused it. `last: stopped: no list` with `tasks open: 0 of 0` means the model has not created a list in this session. `last:` only changes on a reply that ends a run, so it can lag a turn behind the counts |
 | The model asked for a person | It called `todo_loop_block` with a reason, so the loop is stopped until your next message. The reason appears in `/todoloop` as `waiting for you: …` |
-| It stopped at the round cap | The budget for that message is spent; send another message. `list unchanged for N settles` means the model was working without updating the list; `the agent stalled and may need a person` means it stopped without moving the list on the last round — ask what it is waiting on |
-| Rounds jump by two, or continuations appear twice | Two continuation extensions are installed; `pi list` shows them, remove one, then `/reload` |
+| It stopped at your `maxRounds` limit | Only happens when `maxRounds` is set: the continuations for that message are used up; send another message. `no todo change for N replies` means it was working without updating the list; `the agent may need you` means it stopped twice in a row without doing anything — ask what it is waiting on |
+| Continuations jump by two, or the same reply appears twice | Two continuation extensions are installed; `pi list` shows them, remove one, then `/reload` |
 | The list is stale | The extension nudges, it does not write statuses. Nothing here fabricates progress |
-| A warning says the list was cleared by todo alone | Every task closed in a turn with no other tool work. Check the work before trusting it |
+| No status or warning appears | `/todoloop` and the warnings need a UI. In `pi -p` and `--mode json` the loop still runs, but the only controls are the kill-switch file and `maxRounds` |
+| A warning says tasks were deleted | The list was emptied by a turn whose only tool was `todo`, and that turn deleted tasks rather than completing them. Check the work before trusting it |
 
 ## Uninstall
 
@@ -156,16 +165,16 @@ hidden continuation entries.
 
 ## Requirements
 
-- **pi 1.5.0** (tested; needs the `turn_end` boundary).
+- **pi 1.5.1** (tested; needs the `turn_end` boundary).
 - **A todo tool** named `todo` that stores its list in the session — tested with
   `@juicesharp/rpiv-todo` 2.15.0.
 - **Node 22.19+**, the floor pi itself requires. The extension has no dependencies.
 
-Last verified 2026-11-04; the exact table and what was checked is in
+Last verified 2026-11-10; the exact table and what was checked is in
 [docs/pi-api-alignment.md](docs/pi-api-alignment.md).
 
-Install only one continuation extension: a second one that also requests turns makes the counters and
-the budget meaningless.
+Install only one continuation extension: a second one that also requests turns doubles every
+continuation and makes the counts meaningless.
 
 ## Further reading
 

package/docs/behaviour.md

@@ -42,16 +42,24 @@ the object it already was — not re-built, not extended.
 ## Stalls, and the block tool
 
 Nothing here stops the loop for being quiet. A model that keeps answering without moving the list is
-kept alive until the round cap, because "stuck" and "waiting for a person" look identical from the
-outside — and one of them must not be punished.
-
-- A **settle** whose task signature is unchanged increments `stalled`; a settle that changed the list
-  resets it. The counter has no cap: it decides *when to ask*, not when to give up.
-- On the first settlement since progress that finds `stalled >= 1` — one stop that did not move the
-  list — the nudge is the variant that adds *"If you cannot proceed without a person, call
-  `todo_loop_block` with the reason."* It is offered **once per stall**; tool work re-arms it, so a
-  second, separate stall after real progress is a new question.
-- A **tool turn** clears `stalled`. Work is progress even when the list was not touched.
+kept alive — until the list clears, the agent asks for a person, you stop it, or a cap you configured
+is reached — because "stuck" and "waiting for a person" look identical from the outside, and one of them
+must not be punished. Without a cap that means it keeps costing turns; every tenth settle since the list
+last changed raises a warning, so a frozen list — the shape this package exists for — does not run
+invisibly either.
+
+- A **settle** whose task signature is unchanged increments `staleSettles`; a settle that changed the
+  list resets it. `settleRun` counts assistant turns since the last tool turn, and it is that counter —
+  not `staleSettles` — that decides *when to ask*.
+- **The nudge has two variants.** The plain one says continue and use the todo tool. The second adds
+  *"If you cannot proceed without a person, call `todo_loop_block` with the reason."*, and is used for
+  exactly one shape: the model stopped, we sent one request, and it stopped again **without running a
+  tool and without the list changing** (`settleRun === 2`). `settleRun` counts assistant turns since the
+  last tool turn, so work in between restarts it — that stop gets the plain nudge, and the stop after it
+  is asked instead. Because the run keeps growing, one stall asks once rather than on every stop.
+- A **tool turn** resets `settleRun`, so the next stop is not asked about even
+  when the list was not touched. A tool turn that ends `error`/`aborted` resets it too: it is still a
+  request between two stops.
 - **`todo_loop_block`** is the agent's own exit. It is advertised in the prompt from the first turn —
   pi lists it in `<tools>` and carries its guideline in `<rules>`, because the tool declares a
   `promptSnippet` — and the nudge is the timed offer, not the only way to learn it exists. It takes a
@@ -62,29 +70,35 @@ outside — and one of them must not be punished.
   The tool also refuses while the loop is paused or a kill switch is present, and says so, so a
   disabled extension never notifies or writes state.
 - **`staleSettles`** counts settles since the list last changed; a tool turn that leaves the list
-  unchanged does not clear it. It
-  never injects anything and never stops anything: it only decorates the reason string
-  (`, list unchanged for N settles`) so a burn through the round cap does not read like healthy work.
-- **A list cleared by `todo` calls alone is announced.** If every task goes from open to closed in a
-  turn whose only tool results were `todo`, a warning says so once. The loop's success state and its
-  failure state are the same observable.
+  unchanged does not clear it. It never injects anything and never stops anything: it only decorates
+  the reason string
+  (`, no todo change for N replies`) so a burn to a configured cap does not read like healthy work.
+- **Deleting the list is announced; finishing it is not.** If every task goes from open to closed in a
+  turn whose only tool results were `todo`, the *calls* decide the message: a `delete` in that turn
+  produces a warning naming how many tasks were thrown away, because a deleted task is not finished
+  work. `completed` calls say nothing — finishing work and ticking the boxes in one turn is the normal
+  ending. Calls are counted rather than the snapshot's rows, because rpiv-todo keeps deleted tasks as
+  tombstones in every later snapshot; `clear` is announced the same way, since it empties the list
+  without completing anything; a result with no `action` at all falls back to the vague wording, since
+  there is nothing to inspect.
 
 ## Counters
 
 | Counter | Meaning | Reset by |
 |---|---|---|
 | `rounds` | continuations spent for the current human message | a new human message, `/todoloop reset`, a new process |
-| `stalled` | settles in a row that left the list unchanged — no cap; it decides when the block hint is offered | the list changing, a completed tool turn, a new human message |
-| `staleSettles` | settles since the list last changed | the list changing, a new human message |
+| `staleSettles` | settles since the list last changed — decorates the cap reason and drives the every-tenth warning | the list changing, a new human message |
+| `settleRun` | assistant turns since the last tool turn — `2` is the stop the hint asks on | any tool turn, a new human message, `/todoloop reset` |
 
 - **One budget per human message.** A user-role message carrying a `customType` (this extension's
   marker, another extension's hidden message) is skipped when choosing the anchor, so it does not reset
   the budget; `/todoloop` prints the anchor it is using.
 - **A stop keeps the budget shut.** Hitting the cap does not clear the counters, so
-  another extension's continuation or a provider retry under the same message cannot re-arm 12 rounds.
+  another extension's continuation or a provider retry under the same message cannot re-arm the budget.
   A queued human message is a new anchor and resets the budget the ordinary way.
-- **A stale list stops on the cap**, never earlier: any tool turn clears the stall. That is why the cap
-  reason appends `, list unchanged for N settles`.
+- **A stale list burns to the cap when one is set**, never earlier: only the list changing clears the
+  count — a tool turn does not reach the decision at all. That is why the cap reason appends
+  `, no todo change for N replies`.
 - **Errors do not close the budget.** A turn that ends `error` or `aborted` stops the loop for that turn
   and spends no round; the counters are left as they are, so the next settle under the same message can
   continue — which is what a provider retry hits.
@@ -98,11 +112,11 @@ outside — and one of them must not be punished.
 
 | `last:` | Meaning |
 |---|---|
-| `continuing: round 1/12, 2 open` | working as intended |
+| `continuing: 2 tasks still open, continue 1` | working as intended (`continue 1/12` when `maxRounds` is set) |
 | `stopped: list is clear` | every remaining task is `completed`; a list whose tasks are all `deleted` reports `no list` instead |
 | `stopped: no list` | no recognised todo state on the branch — see the five causes below |
 | `waiting for you: waiting on Dana's review` | the agent called `todo_loop_block`; your next message resumes |
-| `stopped: round cap 12 reached, 2 open` | the budget is spent; `, list unchanged for N settles` means it worked without updating the list, `, the agent stalled and may need a person` means the last round was one stop that did not move the list |
+| `stopped: 12 continuations used, 2 tasks still open` | the budget is spent; `, no todo change for N replies` means it worked without updating the list, `, the agent may need you` means it stopped on a bare stall |
 | `stopped: turn outcome was error` / `aborted` | the provider failed, or you aborted the turn |
 | `paused by user` | `/todoloop pause`; `/todoloop resume` or restart |
 | `resumed by user` | `/todoloop resume`, or the human's next message clearing a pending block; the next settle may continue |
@@ -151,23 +165,28 @@ task `deleted`.
 ## Configuration limits
 
 Invalid config never fails a turn: missing, unreadable or invalid values fall back to the defaults.
-That includes values below `1` — `"maxRounds": 0` means "use 12", not "never continue". Numbers are
-clamped so a typo cannot defeat the cap it configures: `maxRounds` ≤ 1000.
+`maxRounds` is `null` by default, which means no limit: the loop ends when the list clears, the agent
+blocks, or you stop it. Set a number to bound what one message of yours can cost; it is clamped so a
+typo cannot defeat it (`maxRounds` ≤ 1000), and a value below 1 stays unlimited rather than becoming
+"never continue".
 
 ## Cost
 
 - A continuation is a normal model turn: the whole conversation is sent again, so cost scales with the
-  number of continuations × session size. `maxRounds` caps continuations, not turns — tool turns are
-  pi's own and unbounded, so a long tool-heavy stretch can be many turns for one round. That is the
-  dominant term.
+  number of continuations × session size — and each continuation lengthens the conversation the next
+  one re-sends, so a runaway grows faster than that product suggests. With the default there is no
+  continuation cap, so a model
+  that keeps stopping without moving the list keeps costing turns until the list clears or you stop
+  it; set `maxRounds` if you want a limit. Tool turns are pi's own and unbounded either way, so a
+  long tool-heavy stretch can be many turns for one round.
 - The extension adds one short marker per continuation (~40 tokens), plus one constant tool declaration
   and the prompt entries pi derives from it — `<tools>` line, `<rules>` guideline, description and
   schema, roughly 700 characters together, in every request. None of it carries task state, and there
   is no per-request block. Neither the snippet nor the guideline is gated by the kill switch or
   `/todoloop pause`; only the hooks and the call itself are. Whatever the model needs it reads with the `todo` tool, and that result
   is part of its own conversation rather than a parallel copy.
-- `context` walks the branch and returns `undefined` unless a marker actually has to be removed, so on
-  a normal turn it costs one projection pass. `turn_end` reads the config, probes the kill switches and
+- `context` never reads the branch: it returns `undefined` unless one of its own markers has to be
+  removed, so a normal turn costs one pass over the message list. `turn_end` reads the config, probes the kill switches and
   walks the branch on every turn.
 
 ## More

package/docs/pi-api-alignment.md

@@ -5,11 +5,11 @@ versions that was established against.
 
 | Component | Tested version | Recorded in |
 |---|---|---|
-| `@earendil-works/pi-coding-agent` | **1.5.0** | `PI_API_SNAPSHOT` in `src/index.ts` |
+| `@earendil-works/pi-coding-agent` | **1.5.1** | `PI_API_SNAPSHOT` in `src/index.ts` |
 | `@juicesharp/rpiv-todo` | **2.15.0** | this file (item 12) |
-| Node | 22.23.2 | README *Requirements* |
+| Node | 22.23.2 | README *Requirements* (which states the floor, 22.19+) |
 
-Last verified **2026-11-04**. Bump a row here, its constant where one exists, and the README table in
+Last verified **2026-11-10**. Bump a row here, its constant where one exists, and the README table in
 the same commit as the change that depends on it.
 
 The contract is followed where it is documented: `turn_end` boundary proposals, draft entry types,
@@ -35,7 +35,8 @@ full. Items that produce no signal in the transcript are marked _(silent)_.
    what keeps the conversation alternating: `assistant → marker(user) → assistant`. Removing them
    exposes runs of consecutive assistant messages, which alternation-requiring providers reject — a
    stricter risk than the one marker-per-round growth they cost (about 200 bytes each, bounded by
-   `maxRounds` per human message, and they accumulate across messages). Their body is constant (`<todo_loop_continue/>`), so a marker left in
+   `maxRounds` per human message — and only when `maxRounds` is set, since the default is no cap, and they accumulate across messages). Their body is one of two fixed sentences (the plain nudge, or the plain nudge plus the
+   `todo_loop_block` clause), so a marker left in
    history cannot claim the loop is on some other round. With the kill switch set the hook rewrites
    nothing, because a disabled extension must not touch the request.
 3. **Two different tails are in play, and only one of them is constrained.** pi's boundary checks the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dumbmice/pi-todo-loop",
-	"version": "0.2.1",
+	"version": "0.3.1",
 	"description": "Keep pi working while a todo list still has open tasks, and stop when the agent asks for a person.",
 	"type": "module",
 	"license": "MIT",

package/src/config.ts

@@ -20,6 +20,10 @@ function coerce(raw: unknown): Partial<LoopConfig> {
 			? Math.min(Math.floor(value), ceiling)
 			: undefined;
 
+	// `null` is the documented "no limit"; a number is clamped so a typo cannot defeat the
+	// budget it configures (`maxRounds: 1e9` would otherwise be honoured). A value below 1
+	// is ignored and stays unlimited, which is also the default.
+	if (record.maxRounds === null) out.maxRounds = null;
 	const maxRounds = bounded(record.maxRounds, 1_000);
 	if (maxRounds !== undefined) out.maxRounds = maxRounds;
 

package/src/index.ts

@@ -5,8 +5,8 @@
  *
  *   context    drop a marker that would sit next to a human message, and
  *              nothing else: the prompt is never rewritten with task state
- *   turn_end   request another turn while tasks are open, bounded by maxRounds
- *              (see loop.ts), and stop when the agent calls todo_loop_block
+ *   turn_end   request another turn while tasks are open (uncapped unless maxRounds is
+ *              set), and stop when the agent calls todo_loop_block
  *   todo_loop_block  the agent's "I need a person" signal, scoped to one message
  *   /todoloop  status | pause | resume | reset
  *
@@ -14,7 +14,7 @@
  *
  *   - A `turn_end` continuation must leave the final message role != assistant,
  *     so one entry is mandatory (`_buildBoundaryContext().canContinue` in pi
- *     1.5.0). We append a `custom_message` with `display: false`.
+ *     1.5.1). We append a `custom_message` with `display: false`.
  *   - Markers are never added to a request by this extension, and are only removed
  *     when one would sit next to a human message. A marker at the tail is the nudge.
  *   - pi's non-assistant requirement binds the *persisted projection* checked at
@@ -27,7 +27,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { loadConfig } from "./config.ts";
-import { decide, initialState, type LoopState } from "./loop.ts";
+import { decide, initialState, plural, type LoopState } from "./loop.ts";
 import { readSnapshot } from "./state.ts";
 
 /**
@@ -37,7 +37,7 @@ import { readSnapshot } from "./state.ts";
  * No pi type import on purpose: the extension is loaded by pi and the type
  * package would otherwise need to be a dependency, for one signature.
  */
-export const PI_API_SNAPSHOT = "1.5.0";
+export const PI_API_SNAPSHOT = "1.5.1";
 
 /** The part of `ExtensionContext` this extension reads. */
 interface SessionContext {
@@ -60,9 +60,10 @@ export const MARKER_BODY =
 	"Continue with the open todo tasks; use the todo tool to read and update the list. If the human's latest instruction says to stop or limits what to do, do that instead.";
 
 /**
- * The same nudge, offered once per stall: this is the first stop since real progress
- * that did not move the list, which is what a blocked agent looks like. The concession
- * stays last — the block still ends by telling the model the human outranks it.
+ * The same nudge for the first settle since progress that did not move the list — the shape
+ * a blocked agent has. It is offered on exactly one request: repeating it would be pressure
+ * rather than information. The concession stays last, so the block still ends by telling the
+ * model the human outranks it.
  */
 export const MARKER_BODY_HINT =
 	"Continue with the open todo tasks; use the todo tool to read and update the list. If you cannot proceed without a person, call todo_loop_block with the reason. If the human's latest instruction says to stop or limits what to do, do that instead.";
@@ -249,17 +250,28 @@ export default function todoLoop(pi: any, options: TodoLoopOptions = {}): void {
 		// A tool turn is *work*, so it clears the stall counter and re-arms the block
 		// hint: an agent that keeps working is not stuck, and a later stall is a new
 		// question rather than a repeat of the old one.
-		// A list that goes open -> clear in a turn whose only tool calls were `todo` is
-		// the loop's success state and its failure state at once. Never police it;
-		// just do not launder the trust: say so once.
+		// A list that empties in a turn whose only tool calls were `todo` is the loop's success
+		// state and its failure state at once. Never police it — but do not launder the trust.
+		// Count *calls*, not snapshot rows: rpiv-todo keeps deleted tasks as tombstones in every
+		// later snapshot, so counting rows would fire on a completion two turns after a deletion
+		// and would count the same tombstone once per call.
 		if (snapshot.open.length === 0 && state.lastOpenCount > 0 && toolResultCount > 0) {
 			const names = toolResults.map((result) => String((result as Record<string, unknown>)?.toolName ?? ""));
-			const onlyTodo = names.every((name) => name === "todo");
-			if (onlyTodo) {
-				ctx.ui?.notify?.(
-					"todo-loop: the list was cleared by todo calls alone in that turn — no other tool work accompanied it",
-					"warning",
+			if (names.every((name) => name === "todo")) {
+				const actions = toolResults.map((result) =>
+					String(((result as Record<string, unknown>)?.details as Record<string, unknown> | undefined)?.action ?? ""),
 				);
+				const known = actions.some((action) => action !== "");
+				const deleted = actions.filter((action) => action === "delete").length;
+				const line =
+					deleted > 0
+						? `${plural(deleted, "task")} ${deleted === 1 ? "was" : "were"} deleted rather than completed in the turn that emptied the list. A deleted task is not finished work, so check the work before trusting the result.`
+						: actions.includes("clear")
+							? "the todo list was cleared in the turn that emptied it, so nothing there was completed. Check the work before trusting the result."
+							: known
+								? ""
+								: "the todo list emptied in a turn that only ran the todo tool, and its result carries no task list, so there is no way to tell whether tasks were finished or deleted. Check the work before trusting the result.";
+				if (line !== "") ctx.ui?.notify?.(`todo-loop: ${line}`, "warning");
 			}
 		}
 		state.lastOpenCount = snapshot.open.length;
@@ -270,12 +282,13 @@ export default function todoLoop(pi: any, options: TodoLoopOptions = {}): void {
 		}
 
 		if (toolResultCount > 0) {
+			// Any tool turn — even one that failed — is work between two stops, so it ends the
+			// run of settles the hint counts.
+			state.settleRun = 0;
 			if (String(event?.outcome) !== "completed") {
 				state.reason = `stopped: turn outcome was ${String(event?.outcome)}`;
 				return undefined;
 			}
-			state.stalled = 0;
-			state.hintSent = false;
 			return undefined;
 		}
 
@@ -328,6 +341,24 @@ export default function todoLoop(pi: any, options: TodoLoopOptions = {}): void {
 		};
 
 		Object.assign(state, next, { reason: decision.reason });
+		// With no cap by default, a runaway must still become visible. `staleSettles` counts
+		// settles since the list last changed and tool turns do not clear it, so this also
+		// catches the model this package exists for: tools running, list frozen.
+		if (next.staleSettles > 0 && next.staleSettles % 10 === 0) {
+			const open = snapshot.open.length;
+			const tasks = `${open} ${open === 1 ? "task is" : "tasks are"}`;
+			const left = config.maxRounds === null ? 0 : config.maxRounds - next.rounds;
+			const brake =
+				config.maxRounds === null
+					? "Run /todoloop pause to stop it, or set maxRounds in ~/.pi/agent/todo-loop.json to limit how often it continues"
+					: left <= 0
+						? `Your limit is ${config.maxRounds} continuations per message and this message has used ${next.rounds}, so it stops on the next reply`
+						: `Your limit is ${config.maxRounds} continuations per message and this message has used ${next.rounds}, so it can continue ${left === 1 ? "once more" : `${left} more times`}`;
+			ctx.ui?.notify?.(
+				`todo-loop: the agent has replied ${next.staleSettles} times without updating the todo list, and ${tasks} still open. It keeps being asked to continue. ${brake}`,
+				"warning",
+			);
+		}
 		return proposal;
 	});
 
@@ -381,17 +412,18 @@ export default function todoLoop(pi: any, options: TodoLoopOptions = {}): void {
 					: waitingNow
 						? "waiting (the agent asked for you; your next message resumes)"
 						: state.reason.startsWith("stopped:")
-							? "stopped (next human message starts a new budget)"
+							? "stopped (your next message restarts the count)"
 							: "active";
 			ctx.ui?.notify?.(
 				[
 					`todo-loop ${mode}`,
-					`rounds ${state.rounds}/${config.maxRounds} · stalled ${state.stalled}`,
+					`asked to continue: ${state.rounds}${config.maxRounds === null ? " (no limit)" : ` of ${config.maxRounds}`}`,
+					`replies since the todo list last changed: ${state.staleSettles}`,
 					// Only while it still belongs to this message: the human's next one
 					// resumes the loop even though the reason is still in memory.
 					...(waitingNow ? [`waiting: ${(state.waiting as { reason: string }).reason}`] : []),
-					`open ${snapshot.open.length}/${snapshot.tasks.length} tracked`,
-					`anchor ${snapshot.anchor || "(none)"}`,
+					`tasks open: ${snapshot.open.length} of ${snapshot.tasks.length}`,
+					`counting from: your message ${snapshot.anchor || "(none yet)"} — a new message restarts the count`,
 					`last: ${waitingNow ? `waiting for you: ${(state.waiting as { reason: string }).reason}` : state.reason}`,
 					`config ${configPath}`,
 				].join("\n"),

package/src/loop.ts

@@ -10,27 +10,27 @@ export interface LoopState {
 	/** Continuations started since the last human message. */
 	rounds: number;
 	/**
-	 * Consecutive settles that neither ran a tool nor changed the task list. No cap:
-	 * it decides when to offer the block tool, not when to give up.
+	 * Assistant turns since the last tool turn. A stop that follows exactly one other stop —
+	 * `settleRun === 2` — is the one-request-one-stop shape the hint asks about.
 	 */
-	stalled: number;
-	/** Whether the "call todo_loop_block" clause has already been offered this stall. */
-	hintSent: boolean;
+	settleRun: number;
 	/** Task signature at the previous decision, to detect list changes. */
 	lastSignature: string;
-	/** Settles since the list last changed: a stale list stops on the cap. */
+	/** Settles since the list last changed. Drives the every-tenth warning to the human. */
 	staleSettles: number;
 	/** Id of the user message the current budget belongs to. */
 	anchor: string;
 }
 
 export interface LoopConfig {
-	/** Max consecutive auto-continuations per human message. */
-	maxRounds: number;
+	/** Continuations allowed per human message; `null` means no limit. */
+	maxRounds: number | null;
 }
 
 export const DEFAULTS: LoopConfig = {
-	maxRounds: 12,
+	// No cap by default: the loop ends when the list clears, the agent asks for a person,
+	// or you stop it. Set a number to bound what one message of yours can cost.
+	maxRounds: null,
 };
 
 export type DecisionInput = {
@@ -58,9 +58,8 @@ export interface Decision {
 	reason: string;
 	/**
 	 * True when this continuation should carry the "if you cannot proceed without a
-	 * person, call todo_loop_block" clause. Offered once per stall: this is the first
-	 * stop since real progress that did not move the list — the shape a blocked agent
-	 * has.
+	 * person, call todo_loop_block" clause: the first settle since real progress that did
+	 * not move the list. One request, not a series.
 	 */
 	hint: boolean;
 }
@@ -82,13 +81,22 @@ function stop(state: LoopState, reason: string): Decision {
  * Order matters: a new human message resets the budget before anything else, so
  * a long conversation cannot inherit the previous turn's spent rounds.
  */
+export const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? "" : "s"}`;
+
 export function decide(input: DecisionInput): Decision {
 	const { state, config } = input;
 
 	// A new human message owns a fresh budget.
 	let current: LoopState =
 		input.anchor !== state.anchor
-			? { ...state, rounds: 0, stalled: 0, hintSent: false, lastSignature: "", staleSettles: 0, anchor: input.anchor }
+			? {
+					...state,
+					rounds: 0,
+					settleRun: 0,
+					lastSignature: "",
+					staleSettles: 0,
+					anchor: input.anchor,
+				}
 			: { ...state };
 
 	if (input.outcome !== "completed") {
@@ -100,42 +108,42 @@ export function decide(input: DecisionInput): Decision {
 
 	const progressed = input.toolResultCount > 0 || input.signature !== current.lastSignature;
 	if (progressed) {
-		// Work re-arms the hint: a second stall, after real progress, is a new question.
-		current.stalled = 0;
-		current.hintSent = false;
 		current.staleSettles = 0;
 	} else {
 		current.staleSettles += 1;
-		current.stalled += 1;
 	}
 
-	// A repeat stop is the shape a blocked agent has: it already answered once, it did
-	// not move the list, and it stopped again. Offer the block tool there — once per
-	// stall — and never stop the loop for it. The only stops are a clear list, the
-	// round cap, an error, and the agent asking for a person.
-	const hint = current.stalled >= 1 && !current.hintSent;
+	// Every settle counts; a tool turn resets the run. `settleRun === 2` is exactly "it stopped,
+	// we sent one request, and it stopped again" — the shape the hint asks about. A list change
+	// is progress, so it is not asked there either, and the run keeps growing, so one stall asks
+	// once rather than on every stop.
+	current.settleRun += 1;
+	const hint = current.settleRun === 2 && !progressed;
 
-	if (current.rounds >= config.maxRounds) {
+	if (config.maxRounds !== null && current.rounds >= config.maxRounds) {
 		const stale =
-			current.staleSettles >= 2 ? `, list unchanged for ${current.staleSettles} settles` : "";
+			current.staleSettles >= 2 ? `, no todo change for ${current.staleSettles} replies` : "";
 		// A hint that comes due on the cap round has no continuation left to ride in.
 		// Do not drop it silently: the human reads the reason, and the agent may be
 		// blocked rather than done.
-		const stalled = hint ? ", the agent stalled and may need a person" : "";
-		return stop(current, `stopped: round cap ${config.maxRounds} reached, ${input.openCount} open${stale}${stalled}`);
+		const stalled = hint ? ", the agent may need you" : "";
+		return stop(
+			current,
+			`stopped: ${plural(config.maxRounds, "continuation")} used, ${plural(input.openCount, "task")} still open${stale}${stalled}`,
+		);
 	}
 
 	current.rounds += 1;
 	current.lastSignature = input.signature;
-	if (hint) current.hintSent = true;
+	const of = config.maxRounds === null ? "" : `/${config.maxRounds}`;
 	return {
 		continue: true,
 		next: current,
 		hint,
-		reason: `continuing: round ${current.rounds}/${config.maxRounds}, ${input.openCount} open`,
+		reason: `continuing: ${plural(input.openCount, "task")} still open, continue ${current.rounds}${of}`,
 	};
 }
 
 export function initialState(): LoopState {
-	return { rounds: 0, stalled: 0, hintSent: false, lastSignature: "", staleSettles: 0, anchor: "" };
+	return { rounds: 0, settleRun: 0, lastSignature: "", staleSettles: 0, anchor: "" };
 }