@dumbmice/pi-todo-loop 0.2.0 → 0.3.0

package/AGENTS.md

@@ -84,7 +84,11 @@ adding a `CHANGELOG.md` line — all in the same commit.
 - **The only *variable* agent-facing text is the nudge.** One of two fixed sentences, appended once
   per continuation. No state block, no reminder, no per-request rewrite: the list is the agent's to
   read with the todo tool. The tool declaration (`todo_loop_block`) is constant and carries no task
-  state, but it is in every request — count it in cost claims. The non-assistant constraint is pi's `turn_end` projection check, not the request (register
+  state, but it is in every request — count it in cost claims: the declaration plus the one-line
+  `<tools>` snippet and the `<rules>` guideline it earns (a few hundred characters together). It
+  declares a `promptSnippet` and a guideline that names it, because pi only shows a tool in the
+  prompt's `<tools>` list when a snippet exists; without one the exit is in the tool array but absent
+  from that summary. The non-assistant constraint is pi's `turn_end` projection check, not the request (register
   item 3) — do not re-derive a coupling between the two.
 - **One entry per continuation is a floor, not a choice.** pi has no `resume()` that appends nothing.
   Do not try to reach zero entries; keep the single `custom_message` with `display: false`.
@@ -98,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
@@ -123,7 +130,9 @@ adding a `CHANGELOG.md` line — all in the same commit.
   continues, but the loop would then stop silently — inert is better than loud.
 - **Nothing is written.** No files, no network, no process execution. The only reads are the optional
   config, the two kill-switch paths and the session branch.
-- **The kill switch is checked in both hooks and in `todo_loop_block`'s `execute`.** Disabling takes effect on the next request, without
+- **The kill switch is checked in both hooks and in `todo_loop_block`'s `execute`.** It cannot remove
+  the tool from the prompt: pi builds `<tools>`/`<rules>` from the registration, so a disabled session
+  still advertises an exit that will be refused. Disabling takes effect on the next request, without
   `/reload`.
 - **No pi type import; `pi: any` at the registration boundary.** Contexts the file reads are typed
   structurally (`SessionContext`). Adding the pi types would make a dependency out of a package that
@@ -138,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` |
@@ -159,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` |
@@ -169,8 +179,13 @@ introduces an edge.
 | the block's tool turn costs no round, and no marker is written after it | `state machine: the block call's tool turn costs no round, and the settle after it stops` |
 | a model-authored reason is flattened and bounded | `a reason is flattened to one line and bounded` |
 | 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` |
@@ -196,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
 
@@ -205,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
@@ -278,21 +293,32 @@ grep -c 'todo-loop:continue' ~/.pi/agent/sessions/<project>/*.jsonl   # one per
 
 ## Release canary
 
-The one failure this suite cannot see is pi changing how a `display: false` `custom_message` projects,
-or tightening `canContinue`. Drafts are committed before the continuation is validated, so that change
+Two failures this suite cannot see. The first is pi changing how a `display: false` `custom_message`
+projects, or tightening `canContinue`; the second is how pi renders a custom tool into the system
+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:
 
 ```bash
-pi -e . -p "create two todos 'a' and 'b', then reply ok" --tools todo
+# `-ne` because the released copy registers the same tool name: `pi -e .` next to the installed
+# version fails with `Tool "todo_loop_block" conflicts with …`.
+pi -ne -e . -p "create two todos 'a' and 'b', then reply ok" --tools todo
 grep -c 'todo-loop:continue' ~/.pi/agent/sessions/--<project>--/*.jsonl   # 0 is a failure
 ```
 
-and read the pi changelog for `custom_message`, `display`, `canContinue`, plus rpiv-todo's for
-`reminder` (upstream PR #190 would put a second task block in the request).
+For the prompt half, run with `--mode json` and confirm the tool reached the system prompt section:
+
+```bash
+pi -ne -e . --mode json -p "reply ok" | grep -o 'todo_loop_block: Stop the todo loop'
+```
+
+and read the pi changelog for `custom_message`, `display`, `canContinue`, `promptSnippet`,
+`promptGuidelines`, plus rpiv-todo's for `reminder` (upstream PR #190 would put a second task block in
+the request).
 
 ## Known limitations to revisit
 
@@ -300,7 +326,7 @@ and read the pi changelog for `custom_message`, `display`, `canContinue`, plus r
   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.
@@ -351,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.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
+
+- `todo_loop_block` now declares a `promptSnippet` and a `promptGuidelines` bullet, so pi lists it in the
+  system prompt's `<tools>` section and its guideline in `<rules>`. Before this the tool was in the
+  request's tool array but absent from the prompt summary, so an agent could only find it through the
+  nudge. The guideline also tells the model to pick a reasonable option and state its assumption when a
+  choice is its own, rather than asking a person.
+
 ## [0.2.0] - 2026-11-05
 
 ### Added
@@ -133,4 +179,7 @@ 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
+[Unreleased]: https://github.com/DumbMice/pi-todo-loop/compare/v0.3.0...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,26 +61,32 @@ 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
-(`todo_loop_block`, which carries no task state), so the list stays the agent's to maintain and the
-conversation stays yours.
+*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
 
@@ -161,11 +170,11 @@ hidden continuation entries.
   `@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-06; 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,47 +42,63 @@ 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.
-- **`todo_loop_block`** is the agent's own exit. It takes a reason, stores `{reason, anchor}` in memory
-  and stops continuations for that message. The human is notified, `/todoloop` shows
+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
+  reason, stores `{reason, anchor}` in memory and stops continuations for that message. The human is notified, `/todoloop` shows
   `waiting for you: <reason>`, and the human's next message is a new anchor, so the block clears itself
   — there is no unblock call.
 - A block with an empty reason is refused, and the loop keeps running: the reason is the whole point.
   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.
@@ -96,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 |
@@ -149,21 +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.
-- The extension adds one short marker per continuation (~40 tokens) plus one constant tool declaration
-  (`todo_loop_block`, a few hundred characters of description and schema) that pi puts in every
-  request. Neither carries task state, and there is no per-request block. Whatever the model needs it reads with the `todo` tool, and that result
+  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

@@ -7,9 +7,9 @@ versions that was established against.
 |---|---|---|
 | `@earendil-works/pi-coding-agent` | **1.5.0** | `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-06**. 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
@@ -71,7 +72,10 @@ full. Items that produce no signal in the transcript are marked _(silent)_.
 9. **`sendUserMessage` and `Agent.prompt` are deliberately not used.** `sendUserMessage` would add a
    visible user-role message per continuation and pollute the transcript; calling the agent directly
    bypasses `AgentSession` lifecycle handling (busy state, queuing, retry, abort).
-10. **The kill switch is checked in both hooks and in the block tool, not once at load.** Removing it or creating the file
+10. **The kill switch is checked in both hooks and in the block tool, not once at load.** It cannot
+    withdraw the tool's prompt entry: pi renders `<tools>`/`<rules>` from the registration, so a
+    disabled session still shows an exit whose call is then refused with "not running". Removing it
+    would need `pi.setActiveTools` from a hook — a new coupling we did not take for this. Removing it or creating the file
    takes effect on the next request, without `/reload`.
 11. **No dependency on `@earendil-works/pi-coding-agent`, and no peer declaration for it.** Nothing
     here imports the package: the boundary is typed `pi: any` and contexts are typed structurally

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dumbmice/pi-todo-loop",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"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
  *
@@ -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";
 
 /**
@@ -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.";
@@ -127,6 +128,13 @@ export default function todoLoop(pi: any, options: TodoLoopOptions = {}): void {
 		label: "Block the todo loop",
 		description:
 			"Stop the automatic continuation loop for the rest of this message because you need a person: a decision, a review, a credential or information only the human has. The human is shown your reason and their next message resumes the loop. Use it only when you cannot proceed on the open tasks without them.",
+		// Without a snippet pi leaves the tool out of the prompt's `<tools>` summary; it is
+		// still in the request's tool array, but a model reading the prompt summary does not
+		// see the exit until the nudge names it. The exit must not be hidden that way.
+		promptSnippet: "Stop the todo loop for this message and ask the human for what you need",
+		promptGuidelines: [
+			"Use todo_loop_block when you cannot proceed on the open todo tasks without a person — a decision, a review, a credential or information only they have. If the choice is yours to make, pick the reasonable option and say what you assumed instead. Do not use it to end work you could finish yourself.",
+		],
 		parameters: {
 			type: "object",
 			properties: {
@@ -242,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;
@@ -263,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;
 		}
 
@@ -321,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;
 	});
 
@@ -374,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: "" };
 }