@dumbmice/pi-todo-loop 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# @dumbmice/pi-todo-loop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@dumbmice/pi-todo-loop)](https://www.npmjs.com/package/@dumbmice/pi-todo-loop)
+[![license](https://img.shields.io/npm/l/@dumbmice/pi-todo-loop)](https://github.com/DumbMice/pi-todo-loop/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@dumbmice/pi-todo-loop)](https://github.com/DumbMice/pi-todo-loop/blob/main/package.json)
+[![tests](https://github.com/DumbMice/pi-todo-loop/actions/workflows/test.yml/badge.svg)](https://github.com/DumbMice/pi-todo-loop/actions/workflows/test.yml)
+
+Keeps the [pi coding agent](https://pi.dev) working while its todo list still has open tasks.
+
+`rpiv-todo` gives the agent a task list and shows it to you. It never asks pi for another turn, so the
+agent still stops halfway and hands control back. This extension adds the turn: while tasks are open it
+keeps the agent going, puts the list back in front of the model after a compaction, and stops when you
+clear the list.
+
+## Quick start
+
+```bash
+pi install npm:@juicesharp/rpiv-todo    # the list this reads (skip if installed)
+pi install npm:@dumbmice/pi-todo-loop
+```
+
+Then start a session and ask for something with several steps:
+
+```text
+Use the todo tool to plan this, then work through it: make the reports page
+export CSV, add tests, and update the docs.
+```
+
+There is nothing else to configure. `/todoloop` shows what it is doing; `touch
+~/.pi/agent/todo-loop-off` turns it off.
+
+## What it looks like
+
+```text
+you:  make the whole sequence web-editable, then expose it in the browser
+
+pi:   [todo: 12 tasks created, first marked in_progress]
+pi:   T5 backend is in and verified. Committing a report of the state …
+      ← without this extension the run ends here, with 11 tasks open.
+
+pi:   [todo: T5 completed, T6 in_progress]
+pi:   T6 audio/face lanes wired. T7 per-camera PNG export next …
+
+pi:   [todo: all 12 completed]
+pi:   All 12 tasks are complete; here is what was verified …
+      ← the list is clear, so the loop stops and stays stopped.
+```
+
+It stops for three reasons, and `/todoloop` always says which:
+
+| Why it stopped | What you see |
+|---|---|
+| the list is clear | `stopped: list is clear` — the normal ending |
+| the model stopped working the list | `stopped: 2 consecutive turns with no progress, 3 open` — two quiet turns in a row |
+| the budget is spent | `stopped: round cap 12 reached, 3 open` — 12 continuations for your one message |
+
+## When it helps
+
+- Long, multi-step work where the agent summarises and hands back halfway.
+- Sessions long enough to be compacted — the list survives on disk, but the model loses it.
+- A model that runs tools but rarely updates its list. It will still be nudged; it may keep working to
+  the round cap.
+
+## When it does not
+
+- **No todo tool installed.** The extension is inert: nothing continues, nothing is injected.
+- **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 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 will hold, and those refusals cost up to 12 turns.
+
+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.
+
+## Configuration
+
+Optional, at `~/.pi/agent/todo-loop.json`:
+
+```json
+{
+  "maxRounds": 12,
+  "maxStrikes": 2,
+  "injectState": true,
+  "maxInjectedTasks": 6
+}
+```
+
+| Key | Default | What it does |
+|---|---|---|
+| `maxRounds` | `12` | continuations allowed per message to the agent |
+| `maxStrikes` | `2` | turns in a row that leave the list unchanged before stopping |
+| `injectState` | `true` | put the open-task list into each request; `false` leaves the model to read the list itself |
+| `maxInjectedTasks` | `6` | rows shown before `… and N more` |
+
+A missing or broken file falls back to these values; a bad config never fails a turn.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/todoloop` | status: mode, rounds, strikes, open tasks, why it last stopped, config path |
+| `/todoloop pause` | stop continuing and stop injecting, until you resume or restart |
+| `/todoloop resume` | allow the next turn to continue again |
+| `/todoloop reset` | clear the counters and start the budget over |
+
+**Kill switch** — checked before every decision:
+
+```bash
+touch ~/.pi/agent/todo-loop-off     # everywhere
+touch .pi/todo-loop-off             # this project only
+```
+
+## Is it working?
+
+After a response that made no tool calls while tasks are open, `/todoloop` should read something like:
+
+```
+todo-loop active
+rounds 1/12 · strikes 0/2
+open 2/5 tracked · inject on
+anchor 4f3c1a2e
+last: continuing: round 1/12, 2 open
+config ~/.pi/agent/todo-loop.json
+```
+
+To count continuations in a session file:
+
+```bash
+grep -c 'todo-loop:continue' ~/.pi/agent/sessions/<project>/*.jsonl
+```
+
+## Troubleshooting
+
+| Symptom | What to do |
+|---|---|
+| Nothing continues | Check `/todoloop`: `DISABLED` means a kill-switch file exists, `PAUSED` means you paused it, `last: stopped: no list` means no todo tool is writing a list |
+| It stopped with `no progress` | The model answered twice without running a tool or changing the list. Raise `maxStrikes` if you want more attempts |
+| It stopped at the round cap | The budget for that message is spent; send another message. If the reason ends with `list unchanged for N settles`, the model was working without updating the list |
+| Rounds jump by two, or continuations appear 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 |
+
+## Uninstall
+
+```bash
+pi remove npm:@dumbmice/pi-todo-loop
+rm -f ~/.pi/agent/todo-loop.json
+rm -f ~/.pi/agent/todo-loop-off .pi/todo-loop-off
+```
+
+Then `/reload`. Nothing was ever written to your working tree, and old session files keep only the
+hidden continuation entries.
+
+## Requirements
+
+- **pi 1.5.0** (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
+[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.
+
+## Further reading
+
+- **How it behaves, precisely** — counters, markers, the injected block, cost:
+  [docs/behaviour.md](docs/behaviour.md)
+- **pi API alignment** — the deliberate workarounds: [docs/pi-api-alignment.md](docs/pi-api-alignment.md)
+- **Working on the repository**: [AGENTS.md](AGENTS.md)
+- **Changes by version**: [CHANGELOG.md](CHANGELOG.md)
+- **Why it exists** — the upstream issues:
+  [rpiv-mono#159](https://github.com/juicesharp/rpiv-mono/issues/159),
+  [#222](https://github.com/juicesharp/rpiv-mono/issues/222),
+  [#259](https://github.com/juicesharp/rpiv-mono/issues/259)
+
+## License
+
+MIT. Source and issues: <https://github.com/DumbMice/pi-todo-loop>.

package/docs/behaviour.md

@@ -0,0 +1,168 @@
+# How it behaves, precisely
+
+The mechanics behind [README](../README.md). Read this when you are debugging behaviour, deciding
+whether to change a default, or wondering why the loop did something. It assumes you know that a
+**settle** is a model response with no tool calls — the only turn that can end a run.
+
+## The turn it adds
+
+`rpiv-todo` renders and stores the list but never asks pi for another turn. Pi ends a run when the model
+answers with no tool calls. This extension hooks that boundary: while the branch has open tasks it
+requests one more turn, so the model continues instead of handing control back.
+
+Two consequences follow from that being the only mechanism available:
+
+- **A continuation is a persisted entry.** pi has no "resume without appending anything", so each
+  continuation writes one `custom_message` with `display: false` and a constant body that states the
+  instruction (`Continue with the open todo tasks…`). It is invisible in the TUI, but it is in the
+  session file and, when no block is injected, it is what the model reads.
+- **Only a settle spends a round.** `turn_end` fires after every assistant response, including one that
+  ended in a tool call; those already cause pi's next request, so they cost nothing and write no marker.
+  A round, a strike and a marker therefore always concern a turn that would otherwise have ended the run.
+
+## Markers and role alternation
+
+A marker sits between two assistant turns, which is what keeps the conversation alternating: a request
+that contained `assistant → assistant` in a row is rejected by alternation-requiring providers.
+
+The `context` hook therefore keeps a marker only where it separates two assistant turns, and drops it
+when either neighbour is user-role: at the tail, immediately before your own message, or in a run of
+markers. The block replaces a marker tail, merges into a `user`/`custom` tail, and is appended after an
+assistant or toolResult tail.
+
+One exception is documented: `bashExecution`, `branchSummary` and `compactionSummary` tails cannot take
+a merge — pi rebuilds those from their own fields and ignores `content` — so the block becomes a
+separate message there and the request briefly holds two user-role messages. Losing the list on a
+compaction summary would be worse.
+
+## The injected block
+
+While tasks are open, every request ends with an ephemeral `<todo_loop_state>` block: the open tasks with
+their ids and statuses, and an instruction that yields to you. It is never persisted, which is why
+compaction cannot remove it.
+
+- **The block is user-role text and the last thing in the request.** It sits after your newest message
+  and says that your latest instruction outranks it. Models vary in how readily they take that
+  concession: one that reads your "stop" as authoritative will refuse, and those refusals cost up to
+  `maxRounds` turns. That is the same reason `injectState: false` exists.
+- **Task text is sanitised, not interpolated.** Subject, `activeForm` and `status` are model-authored —
+  possibly from a fetched page or a repo file — so every Unicode line terminator flattens, `<` is
+  escaped, controls/bidi/zero-width characters and unpaired surrogates are dropped, and labels truncate
+  by code point. Without this, a task subject could close the tag and forge a directive.
+- **The ids are the todo tool's own**, except where the stored list supplies an unusable or duplicate
+  id: that row moves to a free number so each row can be addressed, which means a `todo` call using the
+  shown number can fail when the tool wrote the list that way.
+- **The block escalates once.** On the first request of a chain it only asks for status
+  moves; from the first continuation onwards it adds a reconciliation clause — *"if this
+  list has drifted from the work, reconcile it now: update statuses, add what is missing,
+  and remove what no longer applies"* — with removal last. A first sighting should not
+  invite reshaping the list; after a nudge that left the list untouched, a drifted list is
+  the likelier explanation. Verified: 115 tests, including both sides of the gate.
+- **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.
+
+## Counters
+
+| Counter | Meaning | Reset by |
+|---|---|---|
+| `rounds` | continuations spent for the current human message | a new human message, `/todoloop reset`, a new process |
+| `strikes` | settles in a row that left the list unchanged | 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 |
+
+- **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 or the strike limit does not clear the counters, so
+  another extension's continuation or a provider retry under the same message cannot re-arm 12 rounds.
+  A queued human message is a new anchor and resets the budget the ordinary way.
+- **A stale list stops on the cap, not on strikes**, because any tool turn clears the strike budget.
+  That is why the cap reason appends `, list unchanged for N settles` — so a stale burn does not read
+  like healthy work.
+- **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.
+- **A stop is announced** once, when the reason changes, so a run cannot end silently on a cap.
+- **Counters live in memory.** `/reload`, a restart or a resumed session starts a new budget and
+  re-reads the list; a pause does not survive either.
+
+### Reason strings
+
+`/todoloop` prints one of these as `last:`. They are also announced when they change.
+
+| `last:` | Meaning |
+|---|---|
+| `continuing: round 1/12, 2 open` | working as intended |
+| `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 four causes below |
+| `stopped: 2 consecutive turns with no progress, 2 open` | the last two settles ran no tool and left the list unchanged |
+| `stopped: round cap 12 reached, 2 open` | the budget is spent; with `, list unchanged for N settles` appended, the model worked without updating the list |
+| `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`; the next settle may continue |
+| `counters reset` | `/todoloop reset` cleared the rounds, strikes and list signature |
+| `idle` | nothing has run yet in this process |
+
+## Where the list comes from
+
+The list is read from the session branch on every request, never cached: a `rpiv-todo-state` custom
+entry's `data.tasks`, or a `todo` toolResult's `details.tasks`, whichever is newer.
+
+That is deliberate. A cache would owe invalidation on session switch, branch, compaction, process start
+and fork; and a resumed session with an open list would report `no list` until the model happened to
+call `todo` — the failure this package exists to prevent. The cost is one backward walk of the branch,
+sub-millisecond on thousands of entries.
+
+Two deviations follow from it:
+
+- **The branch is not the model's context.** After a compaction the model's context drops older
+  entries, but the reader still walks the whole branch, so `/todoloop` can report open work the model
+  has no list for. The panel and the model can disagree.
+- **A newer malformed entry is skipped** in favour of an older valid one, so after a shape change the
+  reader serves the list as of that change. Reading an errored `todo` call as "list clear" would be
+  worse.
+
+`no list` therefore has four causes: no todo tool installed, a tool that is not named `todo`, a shape
+this extension does not recognise, or every task `deleted`.
+
+## Scope
+
+- **A delegated child session runs its own loop.** Each session has its own list and counters, so a
+  subagent that loads this extension can continue independently of its parent; markers do not
+  interleave, but the work can.
+- **`/todoloop` needs an interactive session.** In `pi -p` and `--mode json` the loop runs, but there is
+  no UI for the status or the stop notification; the only signal is the marker count in the session
+  file and the model's final message.
+- **`.pi/todo-loop-off` stops every session started in that directory**; `~/.pi/agent/todo-loop-off`
+  stops all projects; the config file is global and re-read on every request, so editing it affects
+  running sessions.
+- **Nothing is written to your working tree.** The reads are the config, the two kill-switch paths and
+  the session branch.
+
+## 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, `maxStrikes` ≤ 100,
+`maxInjectedTasks` ≤ 50.
+
+## 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, not the
+  block, is the dominant term.
+- `context` reads the config and probes the kill switch, and walks the branch only when it is going to
+  inject. `turn_end` does all three on every turn. While tasks are open the block adds ~100 tokens at
+  the tail; `injectState: false` adds none and leaves the model to call the todo tool's `list` action.
+- One small measurement on `deepseek-flash` (a 2.7k-token session, five turns): ~1,050 uncached input
+  tokens per turn with injection on against ~405 with `injectState: false`, and cache reads occurred in
+  both runs (16.0k vs 36.1k total). The block does not disable the prompt cache, but it and the head
+  rebuild cost a few hundred uncached tokens per request. An order of magnitude, not a benchmark — the
+  two runs took different trajectories.
+
+## More
+
+- [pi extension API alignment](pi-api-alignment.md) — the deliberate workarounds, with the pi version
+  each was verified against.
+- [AGENTS.md](../AGENTS.md) — layout, invariants, tests, release process.

package/docs/pi-api-alignment.md

@@ -0,0 +1,134 @@
+# pi extension API alignment
+
+How this extension's use of pi's extension API relates to the documented contract, and which exact
+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` |
+| `@juicesharp/rpiv-todo` | **2.15.0** | this file (item 12) |
+| Node | 22.23.2 | README *Tested against* |
+
+Last verified **2026-11-04**. 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,
+`context` hook ownership of the message list, `display: false`, and `registerCommand`. Nothing here
+calls pi internals; item 1 nonetheless depends on behaviour pi documents nowhere, which is why it is
+listed below rather than assumed.
+
+What is unusual is not the API use but the *shape* of it: this extension exists to perform a
+continuation that pi does not expose as a single operation. Each client-side workaround is listed in
+full. Items that produce no signal in the transcript are marked _(silent)_.
+
+1. **One hidden entry per continuation, and only on a settle.** `turn_end` fires for every assistant
+   response, including one that ended in a tool call; such a turn already causes pi's next request, so
+   the hook returns early and spends nothing. `continue: true` is proposed only when the run would
+   otherwise end, and the proposed
+   projection must end on a message whose role is not `assistant` — otherwise the boundary reports an
+   invalid continuation and drops it. pi offers no `resume()` that appends nothing, so a continuation
+   is always expressed as *one* appended entry. We append a `custom_message` with `display: false`:
+   invisible in the TUI, about 200 bytes per continuation in the journal _(silent in the transcript)_.
+2. **Markers stay in history and are not stripped.** They sit between two assistant turns, so they are
+   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
+   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
+   *persisted projection* when `turn_end` proposes `continue: true`; the appended marker is what
+   satisfies that check for this extension (`_buildBoundaryContext().canContinue`, computed from the
+   committed drafts — any non-assistant final projected message would do, including a queued one). The
+   *provider request* built by the `context` hook is a different list: pi documents no constraint on its
+   final role, and a request ending on the assistant message is a normal continuation — the mechanism
+   used by `pi-invisible-continue`'s `/continue`
+   (<https://github.com/monotykamary/pi-invisible-continue>, not re-tested here). Conflating the two is
+   the mistake this item exists to prevent.
+4. **The block is appended only where it is needed, and it never doubles the tail.** Three
+   configurations get no block: `injectState: false`, a list with no open task, and the kill switch. In
+   the first two the request keeps whatever tail the history has (a marker, an assistant turn, or the
+   human's own message) and the model must call the todo tool's `list` action to learn the list — the
+   one place this extension asks for compliance instead of enforcing state. When a block is added it
+   replaces a tail marker, is merged into a human-role tail, and is appended only after an assistant or
+   tool tail. No request ending on an assistant message has been exercised against a provider in this
+   repository's testing; the live runs used the default configuration.
+5. **Returning a changed list rebuilds the request head.** pi documents that a `context` handler which
+   returns a different message list causes it to replay the current prompt sections and tool
+   declarations into one leading system message ahead of the returned list. The rebuild is lossless
+   (content appended, sections patched, tools resolved) but the head is not byte-identical to the
+   previous request, so a prompt cache keyed on the head can miss. Observed while reading pi 1.5.0's
+   extension runner; not measured in this repository.
+6. **Task state is read from the branch on every request, not cached in memory.** Loop state (counters,
+   anchor, pause) is in memory and therefore resets with the process. No `session_compact`
+   resync handler is needed, and a branch switch cannot leak another branch's tasks. The cost is one
+   backward walk of the active branch per request.
+7. **The marker `customType` is a stable literal, not a constant keyed to the package version.**
+   Sessions written by earlier builds keep filtering correctly after an upgrade.
+8. **Malformed session entries degrade to "no list".** A boundary handler that throws is reported and
+   the turn continues, but the loop would silently stop continuing; failing soft keeps the extension
+   inert instead of noisy.
+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, not once at load.** 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
+    (`SessionContext`), so the only manifest link to the host is `pi.extensions`. A `peerDependencies`
+    entry would assert a module dependency that does not exist and would have no effect regardless —
+    managed installs pass `--omit=peer` and disable peer resolution, and the loader performs no
+    compatibility check. The trade-off of dropping the type import: the compiler does not check event
+    payload shapes, so `npm test` and a real `pi -e` run carry that weight, and the tested pi version
+    is recorded in the table above rather than enforced.
+12. **A declared dependency on rpiv-todo's *persisted shape*, which is not its public API** (checked
+    against `@juicesharp/rpiv-todo` 2.15.0; the symbols named below are that version's). This
+    extension imports nothing from `@juicesharp/rpiv-todo` and therefore declares no dependency on it,
+    but it reads two representations the package writes: `custom` entries with
+    `customType: "rpiv-todo-state"`, and `todo` toolResult `details.tasks`. The package's own issues
+    describe `details` as extension-specific session data, so a change to that shape is not
+    guaranteed to appear in its semver. Consequences, accepted deliberately:
+    - the reader is written defensively (both shapes tried, `subject`/`content` accepted, malformed
+      entries treated as "no list") so a drift degrades to inert rather than throwing in a boundary;
+    - the tested version is recorded above, not enforced;
+    - the parser is duplicated rather than imported. `@juicesharp/rpiv-todo/state/replay.ts` does
+      export `replayFromBranch` and `isTaskDetails`, but a peer import would resolve to nothing under
+      pi's `--omit=peer` installs, and a declared dependency would make pi install a second nested
+      copy of the extension — which registers a duplicate `todo` tool.
+    - failure is currently indistinguishable from "the agent never called `todo`": both report
+      `stopped: no list` in `/todoloop`. Making those cases distinguishable is the next diagnostic
+      improvement, not a compatibility fix;
+    - a *newer* entry whose `tasks` is malformed is skipped in favour of an older valid one, so after a
+      shape change the reader serves the list as of the change. Not treated as authoritative-empty on
+      purpose: an errored `todo` call carries no `tasks`, and reading that as "list clear" would stop the
+      loop on a failed tool call.
+
+13. **The anchor skips user-role messages that carry a `customType`** _(silent)_. `anchorFromEntry`
+    ignores any `role: "user"` message with a string `customType`, which covers this extension's own
+    marker, another continuation extension's hidden resume message, and a command expansion that carries
+    one. The alternative — narrowing the skip to our own marker type — would let another extension's
+    hidden message move the anchor on every continuation and re-arm the budget each round, which defeats
+    the cap; the cost of the broad skip is that such a message does not reset the budget either. That is
+    one budget for one message, self-healing on the next plain message and visible in
+    `/todoloop`'s `anchor` line.
+
+14. **The loop's counters are not reconstructible from the session file** _(silent)_. A `turn_end`
+    handler is handed `outcome`, `entries` and `continue`; what a `-p`/JSON run persists for the event
+    carries only `{type, message, toolResults}`. A session file therefore shows which continuations happened and
+    when, not how many rounds or strikes were left, nor why the loop stopped; that is only visible live
+    through `/todoloop`. Two runs that end for different reasons can look identical on disk.
+
+15. **Three user-role tails cannot take a merge, so the block becomes a second user message there.**
+    pi rebuilds the content of `bashExecution`, `branchSummary` and `compactionSummary` from their own
+    fields and ignores `content`, so writing the block into one of them would delete it. Those three
+    get a separate user message instead, which means the request briefly has two user-role messages in a
+    row. Accepted deliberately: a compaction summary is exactly when the model most needs the list, and
+    losing it silently is worse than an adjacency that providers merge anyway.
+
+16. **The reader walks `getBranch()`, which is not the model-visible context.** pi's compaction-aware
+    projection is `buildContextEntries()`, and a `context_edit` can hide an entry from future model
+    context while it stays on the branch. Reading the branch therefore means the extension can report a
+    task list the model cannot see — after a compaction, or after another extension edited context. Kept
+    deliberately: the newest persisted todo state is the right answer for the loop's counters, and
+    reading the projected context instead would make the list vanish mid-run, which is the failure this
+    package exists to prevent.

package/package.json

@@ -1,6 +1,62 @@
 {
-  "name": "@dumbmice/pi-todo-loop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@dumbmice/pi-todo-loop",
+	"version": "0.1.1",
+	"description": "Keep pi working while a todo list still has open tasks, and keep that list in context across compaction.",
+	"type": "module",
+	"license": "MIT",
+	"author": {
+		"name": "DumbMice",
+		"email": "bangchengyang@hotmail.com"
+	},
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi-coding-agent",
+		"todo",
+		"task-list",
+		"continuation",
+		"agentic-loop",
+		"compaction",
+		"deepseek",
+		"rpiv-todo"
+	],
+	"homepage": "https://github.com/DumbMice/pi-todo-loop#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DumbMice/pi-todo-loop.git"
+	},
+	"bugs": "https://github.com/DumbMice/pi-todo-loop/issues",
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"files": [
+		"src",
+		"scripts",
+		"tsconfig.json",
+		"docs",
+		"README.md",
+		"AGENTS.md",
+		"CONTRIBUTING.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "node --experimental-strip-types --no-warnings --test test/*.test.ts",
+		"typecheck": "tsc -p tsconfig.json",
+		"pack:check": "node scripts/check-pack.mjs",
+		"prepublishOnly": "npm test && npm run typecheck && npm run pack:check",
+		"pretest": "node -e \"const [a,b]=process.versions.node.split('.').map(Number); if(a<22||(a===22&&b<6)){console.error('@dumbmice/pi-todo-loop tests need Node >= 22.6, but node '+process.versions.node+' is first in PATH.\\nPut a newer node first, for example pi own node:\\n  ~/.local/share/pi-node/current/bin'); process.exit(1)}\""
+	},
+	"engines": {
+		"node": ">=22.19"
+	},
+	"devDependencies": {
+		"@types/node": "^22.20.5",
+		"typescript": "^5.9.3"
+	}
+}

package/scripts/check-pack.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Verify the published tarball actually contains what the package promises.
+ *
+ * `npm pack --dry-run` prints a file list and exits 0 even when `files` matches
+ * nothing, so dropping "src" from the manifest used to pass CI while shipping a
+ * package whose `pi.extensions` entry point does not exist. This asserts the
+ * entry point, the docs and the licence are in the tarball.
+ */
+
+import { execFileSync } from "node:child_process";
+import { firstPack } from "./pack-json.mjs";
+
+const REQUIRED = [
+	"src/index.ts",
+	"src/loop.ts",
+	"src/state.ts",
+	"src/inject.ts",
+	"src/config.ts",
+	"docs/pi-api-alignment.md",
+	"README.md",
+	"AGENTS.md",
+	"CONTRIBUTING.md",
+	"CHANGELOG.md",
+	"LICENSE",
+	"tsconfig.json",
+];
+
+const FORBIDDEN = ["test", "test/", ".github", "node_modules", "package-lock.json"];
+
+const raw = execFileSync("npm", ["pack", "--dry-run", "--json"], { encoding: "utf8" });
+const tarball = firstPack(JSON.parse(raw));
+if (!tarball || !Array.isArray(tarball.files)) {
+	console.error("pack check failed — npm pack produced no file list");
+	process.exit(1);
+}
+const files = new Set(tarball.files.map((file) => file.path));
+
+const missing = REQUIRED.filter((path) => !files.has(path));
+if (missing.length > 0) {
+	console.error(`pack check failed — missing from the tarball:\n  ${missing.join("\n  ")}`);
+	const sample = [...files].slice(0, 20).join("\n  ");
+	console.error(`\nfiles present (${files.size}):\n  ${sample}`);
+	process.exit(1);
+}
+
+const entry = JSON.parse(execFileSync("node", ["-p", "JSON.stringify(require('./package.json').pi)"], { encoding: "utf8" }));
+for (const declared of entry.extensions ?? []) {
+	const path = declared.replace(/^\.\//, "");
+	if (!files.has(path)) {
+		console.error(`pack check failed — pi.extensions declares ${path}, which is not in the tarball`);
+		process.exit(1);
+	}
+}
+
+const leaked = [...files].filter((path) => FORBIDDEN.some((bad) => path === bad || path.startsWith(`${bad}/`)));
+if (leaked.length > 0) {
+	console.error(`pack check failed — dev-only paths in the tarball:\n  ${leaked.join("\n  ")}`);
+	process.exit(1);
+}
+
+console.log(`pack ok: ${files.size} files, entry point and docs present, no dev paths`);

package/scripts/pack-json.mjs

@@ -0,0 +1,33 @@
+/**
+ * Read `npm pack --json`, whose shape changed between npm majors.
+ *
+ * npm 10 returns an array of tarball records; npm 11 returns an object keyed by
+ * package name. The publish workflow upgrades npm, so both shapes appear in practice
+ * and code that destructures `[0]` breaks on the newer one.
+ */
+
+import { execFileSync } from "node:child_process";
+
+/** Normalise either shape to a list of tarball records. */
+export function packEntries(value) {
+	if (Array.isArray(value)) return value.filter((entry) => entry && typeof entry === "object");
+	if (value && typeof value === "object") {
+		return Object.values(value).filter((entry) => entry && typeof entry === "object");
+	}
+	return [];
+}
+
+/** The first packed record, or undefined. */
+export function firstPack(value) {
+	return packEntries(value)[0];
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	const raw = execFileSync("npm", ["pack", "--dry-run", "--json"], { encoding: "utf8" });
+	const record = firstPack(JSON.parse(raw));
+	if (!record || typeof record.filename !== "string") {
+		console.error("pack-json: npm pack produced no tarball record");
+		process.exit(1);
+	}
+	console.log(record.filename);
+}