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

package/AGENTS.md

@@ -0,0 +1,365 @@
+# Working on this repository
+
+Instructions for anyone — human or coding agent — changing `@dumbmice/pi-todo-loop`. For what the extension
+does and how to install it, read [README.md](README.md).
+
+## Layout
+
+```
+src/index.ts              pi wiring: the context hook, the turn_end hook, /todoloop
+src/loop.ts               the pure decision policy (rounds, strikes, anchor reset)
+src/state.ts              reads rpiv-todo state off the session branch
+src/inject.ts             renders the per-request <todo_loop_state> block
+src/config.ts             config load and coercion, defaults on any failure
+test/loop.test.ts         decision policy: caps, strikes, anchor reset, error outcomes
+test/state.test.ts        branch reader: both shapes, recency preference, malformed input
+test/inject.test.ts       renderer and config coercion
+test/index.test.ts        the pi-facing half through a stub `pi`: tail handling, kill switch, caps
+test/state-machine.test.ts the counters as a table of event sequences (the suite to extend)
+test/helpers/harness.ts   the stub `pi`, mutable branch and scripted context those two share
+test/fixture.test.ts      the same hooks over real captured lines (test/fixtures/branch.jsonl)
+test/docs.test.ts         pins the version table, invariant map, reason table, config table, links
+scripts/check-pack.mjs    asserts the published tarball contains what package.json promises
+docs/pi-api-alignment.md  every deliberate workaround over pi's documented extension API
+docs/behaviour.md         how it behaves, precisely: markers, counters, the block, cost
+README.md                 user-facing documentation (what it is, install, config, troubleshooting)
+AGENTS.md                 this file
+CONTRIBUTING.md           four-line pointer to this file (GitHub convention)
+CHANGELOG.md              Keep a Changelog format, released and unreleased entries
+package.json              scripts, engines, the files allow-list, pi.extensions entry point
+tsconfig.json             the strict / noEmit settings used by typecheck
+.github/workflows/        test.yml (Node 22.6, 22 and 24: ci, test, typecheck, pack)
+```
+
+## Requirements and commands
+
+Node >= 22.19 (`engines`, the floor pi itself requires; the entry point is TypeScript and the test
+runner uses `--experimental-strip-types`, which exists from 22.6). **If `npm test` fails with
+`node: bad option: --experimental-strip-types`, a pre-22 node is first in `PATH`** — nvm's v20 shadows
+pi's own node in a typical shell. `pretest` now says so instead of leaking the raw node error. Run the
+publish (and the tests) with pi's node first:
+
+```bash
+export PATH="$HOME/.local/share/pi-node/current/bin:$PATH"
+npm publish --access public
+``` devDependencies stay limited to `typescript` and `@types/node`; the test
+workflow installs with `npm ci`.
+
+```bash
+npm install        # devDependencies only: typescript, @types/node
+npm test           # node:test, no model, no key, no network
+npm run typecheck  # tsc -p tsconfig.json, strict
+npm run pack:check # asserts src, docs, tsconfig, README, AGENTS, CONTRIBUTING, LICENSE, CHANGELOG ship
+
+# one file, while iterating
+node --experimental-strip-types --no-warnings --test test/loop.test.ts
+```
+
+There is no pi install and no build step: the source is TypeScript that pi loads directly, and
+`npm run typecheck` resolves no pi types because the extension imports none.
+
+## Design decisions worth preserving
+
+These are the invariants the suite protects. Changing one means changing its test, any affected
+README text, the matching `docs/pi-api-alignment.md` item (or marking that item inapplicable), and
+adding a `CHANGELOG.md` line — all in the same commit.
+
+- **Merge only into a `user` or `custom` tail.** pi rebuilds `bashExecution`/`branchSummary`/
+  `compactionSummary` content from their own fields and ignores `content`, so merging into those would
+  delete the block; they get a separate message and a documented adjacency (register item 15).
+- **A `todo`-only clear is announced, not policed.** The loop's success and failure states are the same
+  observable; a warning is the most it may do about it.
+- **Task text is model-authored, so it is sanitised, not interpolated.** `sanitizeLabel` collapses
+  flattens every Unicode line terminator, escapes `<`, drops controls/bidi/unpaired surrogates and
+  truncates by code point, because a subject can come from a fetched page and is rendered at the end of
+  a request inside a tag. **`status` is task-authored too** and gets the same treatment. Never render a
+  task field raw.
+- **A marker is kept only where it separates two assistant turns.** There it is the alternation glue;
+  removing it exposes consecutive assistant messages that alternation-requiring providers reject. Any
+  other marker — at the tail, or followed by a human message — is dropped, because it would duplicate a
+  real user turn. The test `no returned request ever contains two adjacent user-role messages` is the
+  general statement; if you change the filter, run it first.
+- **The marker body is constant** (`<todo_loop_continue/>`). It carries no round counter, because a
+  persisted marker must not claim the loop is on round `n` long after that chain ended. Counters live in
+  memory and are reported by `/todoloop`.
+- **The injection is conditional; the marker is not.** The block is appended only when `injectState` is
+  on and tasks are open. 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`.
+- **The marker `customType` is a stable literal.** The tail check must keep recognising markers written
+  by earlier builds; do not derive it from the package name or version.
+- **Task state is read from the branch on every request.** No in-memory cache of the list, no
+  `session_compact` resync handler: memory would drift across forks and compaction. Loop state
+  (counters, anchor, pause) *is* in memory, and a restart necessarily starts a new budget.
+- **The decision is a pure function.** `decide()` in `src/loop.ts` takes a value and returns a value.
+  It must stay free of pi, filesystem and time so the caps can be tested exhaustively.
+- **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 strike are therefore always about a turn that would have ended the run.
+- **A tool turn clears a strike and spends no round** — except a tool turn that ends `error`/`aborted`,
+  which records the stop and leaves the strike budget alone. Tool turns already cause pi's next request, so
+  they must not consume the budget; but they are work, so they reset `strikes`. Without that, a model
+  that runs tools and never updates the list collects two strikes across its settles and stops claiming
+  "no progress" while it was working.
+- **A stop keeps the counters; only a new human message resets them.** Clearing `rounds` / `strikes` 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
+  new anchor, so it resets the budget the ordinary way.
+- **Open means "not finished".** `CLOSED_STATUSES` is an exclusion list (`completed`, `deleted`), not an
+  allow-list: a status the todo tool adds later must not make a task vanish and the loop report the
+  list clear while work remains.
+- **The newer of the two shapes wins.** Custom entry and toolResult fallback are compared by branch
+  position, not by type preference; preference by type would serve a stale list forever if the tool
+  stopped writing custom entries partway through a session.
+- **No runtime dependencies.** The only imports are `node:` builtins. Argument validation, config
+  parsing and rendering are hand-written for that reason.
+- **Fail soft at the boundary.** Parsing a branch, a config file or an entry never throws: malformed
+  input degrades to "no list" or to defaults. A thrown boundary handler is reported and the turn
+  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.** 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
+  deliberately has none.
+
+## Invariant → test map
+
+Find the invariant you are touching, run the case that pins it, and add a neighbour if your change
+introduces an edge.
+
+| Invariant | Pinned by |
+|---|---|
+| 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 turn spends a strike, the second stops | `a text-only turn that changes nothing spends a strike, then stops` |
+| the first sighting of a list is progress, not a strike | `the first sighting of a list counts as progress, not a strike` |
+| a list change resets strikes even with no tool call | `a list change counts as progress even with no tool results` |
+| the round cap stops the loop | `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` |
+| the toolResult fallback works and loses to the custom entry | `falls back to todo toolResult details`, `prefers the custom entry over the toolResult fallback` |
+| the anchor is the newest `role:"user"` message without a `customType` — not assistant, toolResult, our own marker, or another extension's custom user message | `anchor is the newest human message id, ignoring assistant and toolResult`, `our own projected marker never becomes the anchor`, `a user message without an id anchors on its position` |
+| `deleted` tasks leave list, open set and signature | `deleted tasks are excluded from tasks, open and signature` |
+| malformed entries degrade to the empty snapshot | `malformed or missing state degrades to the empty snapshot` |
+| config defaults survive garbage; fields are coerced | `missing or malformed config falls back to defaults`, `valid fields override, invalid ones are ignored` |
+| model-authored task text is sanitised before it enters a request | `a hostile task subject cannot break out of the tag` |
+| the injection shows open tasks only, bounded, `activeForm` for in_progress | `injection lists open tasks with their status`, `injection is bounded and reports the overflow`, `injection uses activeForm only for in_progress`, `injection tolerates an empty subject` |
+| a status change moves the signature | `signature changes when a status changes` |
+| a record with neither a label nor a status is not a task, and arrays are not tasks | `a record with neither a label nor a status is not a task`, `an array element is not a task` |
+| only a `todo` tool's own shapes are read | `a foreign custom entry or toolResult carrying tasks is ignored` |
+| an unknown status counts as open, and status text is normalised | `an unknown status counts as open, not as done`, `status is normalised, so a differently-cased value still closes` |
+| ids are made distinct: a synthetic or colliding id moves to a free number, a unique real id is never renumbered | `a positional id never shadows a real one`, `duplicate ids in the source are made distinct`, `a synthetic id never renumbers a real one, even when it comes first` |
+| a task without a usable id falls back to its position | `a task without a usable id falls back to its position, not to being dropped`, `a null or empty id falls back to the position instead of colliding on 0` |
+| the newer shape wins, in either order | `the newer of a custom entry and a toolResult wins, in either order` |
+| the block is appended only when injecting, replacing a tail marker | `context strips the marker and appends the state block when tasks are open`, `a tail marker is replaced by the block, never followed by it`, `the block is appended when the tail is an assistant turn`, `the request never ends with two user-role messages` |
+| history markers are left in place; they are the alternation glue | `history markers are left alone when nothing is injected`, `history markers are left alone when injection is disabled` |
+| a malformed context payload is not rewritten | `context leaves a malformed payload alone instead of rewriting it` |
+| a task subject cannot break out of the injection tag | `a hostile task subject cannot break out of the tag` |
+| the block ends on the concession, not on a call to act | `the block ends on the concession, not on a call to act` |
+| pause stops the block as well as the continuation | `pause stops both the continuation and the steering block` |
+| 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 a pending strike | `tool turns clear a pending strike but never spend a round` |
+| 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 user-role tail receives the block instead of a second message (marker first dropped) | `a human-role tail receives the block instead of a second user message`, `a marker after a human message still yields one user-role tail` |
+| a malformed event payload does not throw | `turn_end tolerates a malformed event payload instead of throwing` |
+| clamped and invalid config values fall back | `numbers are clamped so a typo cannot defeat the cap it configures`, `a value below 1 is treated as invalid, not as zero` |
+| an errored or aborted turn is never continued | `turn_end stops on an errored or aborted turn and does not spend a round` |
+| the cap and pause gate the loop at the hook level | `the round cap is sticky for one human message`, `pause stops both the continuation and the steering block` |
+| the docs match the code | `the pi snapshot constant appears in the README and the register`, `the verification date appears in the README and the register`, `the tested rpiv-todo version is recorded in both places`, `the CHANGELOG documents the version in package.json`, `every README link target inside the repository exists`, `every test name the invariant map cites actually exists`, `every stop reason the code can report appears in the README table`, `the README configuration table states every default, not just the numbers` |
+
+## Adding or changing a continuation rule
+
+1. Put the logic in `decide()` (`src/loop.ts`), not in the hook. The hook only adapts events and
+   applies the returned state. Add a row to `SCENARIOS` in `test/state-machine.test.ts` for the new
+   behaviour before touching prose.
+2. Add the field to `LoopState` or `DecisionInput` if new information is needed, and make it
+   default-safe: a session recorded by an older build must still decide sensibly.
+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]`.
+
+## Fragile areas
+
+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`, `strikes` 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
+   carries no id; returning `""` would make "no anchor yet" and "this entry had no id"
+   indistinguishable, freezing the per-message reset. A branch switch that lands on a sibling branch
+   with the same newest user entry keeps the spent budget — deliberate, so a fork cannot refill it.
+4. **State shape drift in the todo tool.** Both shapes are read defensively; keep `normalizeTask`
+   tolerant of renamed fields (`content` vs `subject`) and of unusable ids, and keep `withUniqueIds` in
+   `snapshotFrom` — it moves only synthetic or *colliding* ids, never a unique one the payload supplied,
+   because that number is what the model must use to update the task.
+5. **Branch walking.** The reader stops once it holds a list in *either* shape and the anchor. It walks
+   newest-first, so a toolResult newer than the custom entry is already in hand; the extra walking is to
+   reach the anchor, which is older than the newest list entry. Breaking out on the list alone leaves
+   `anchor` empty, which makes every turn look like a new human message and re-arms the full budget each
+   time.
+
+## Tests
+
+`test/*.test.ts` uses `node:test` and imports the source directly; nothing needs a model, a key or a
+network. `test/state-machine.test.ts` is the one to extend when you touch the counters: it replays sequences in
+the vocabulary pi actually produces — `settle` (a response with no tool calls), `tool` (a response that
+ended in tool calls), `edit` (the list changed), `human` (a new message), plus pause/resume/reset/
+error/abort/kill-switch — and asserts the whole outcome at once: continuations, markers, rounds,
+strikes, the reason `/todoloop` prints and its header. Every release-blocking defect in this repository's
+history lived in that interaction, so a new rule belongs there as a row in `SCENARIOS` before it belongs
+in prose.
+
+`test/index.test.ts` fakes pi's surface (an object with `on` and `registerCommand`, plus a
+`SessionContext` over a hand-built branch) and asserts the hook *return values*; it is the only place
+the tail coupling is checked. `test/docs.test.ts` reads the repository's own Markdown, which is how the
+tested-version table is enforced. When fixing a bug, add the failing case first. Run `npm test` before every commit; CI repeats
+it on Node 22 and 24 together with `npm run typecheck` and `npm run pack:check`.
+
+### Try a change locally
+
+There is no build step: pi loads `src/index.ts` through `package.json` → `pi.extensions`.
+
+```bash
+pi -e /absolute/path/to/pi-todo-loop    # one session, straight from the working copy
+```
+
+A live check needs `rpiv-todo` installed and an agent that creates a task list. Ask for two tasks and
+then tell it to stop; with the loop active you should see it continue, and `/todoloop` should report
+`round 1/12`. To watch the hidden machinery:
+
+```bash
+grep -c 'todo-loop:continue' ~/.pi/agent/sessions/<project>/*.jsonl   # one per continuation
+```
+
+## Documentation conventions
+
+- `README.md` is for users of the extension, read top-down on npm: what it does, quick start, one
+  example, when it helps and when it does not, configuration, commands, "is it working", troubleshooting,
+  uninstall, requirements. No implementation inventories, no counter mechanics, no CI or release steps.
+- `docs/behaviour.md` is the depth the README links to: marker lifetime, role alternation, the injected
+  block, counter semantics, reason strings, where the list is read from, scope, cost. Technical, but
+  written for a user debugging behaviour rather than a contributor.
+- `docs/pi-api-alignment.md` is the register of deliberate workarounds over pi's documented extension
+  API, and the record of which versions those were established against. Add an item when behaviour
+  deviates; items with no output signal are marked _(silent)_. The tested-version table at the top,
+  `PI_API_SNAPSHOT` in `src/index.ts`, and the README *Tested against* table move together in the
+  same commit as the change that depends on them, and `test/docs.test.ts` fails if the constant, the
+  date or the tested rpiv-todo version goes missing from either file. Note that `@juicesharp/rpiv-todo`
+  is a *shape* dependency only (register item 12): it is never imported, so it has no `package.json`
+  entry, and its tested version lives in that table rather than in a constant.
+- `CHANGELOG.md` follows Keep a Changelog. Put unreleased work under `[Unreleased]` with
+  Added/Changed/Fixed headings; add the version heading when the release is tagged. `test/docs.test.ts`
+  fails if the published version has no entry, so this one is enforced.
+- `AGENTS.md` (this file) holds contributor, architecture and release material.
+
+## 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
+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
+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
+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).
+
+## Known limitations to revisit
+
+- **The decision is at `turn_end`, one boundary early.** pi 1.5.0 documents `agent_before_settle` as
+  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 strike
+  reset lives in the adapter rather than in `decide()`. Moving the decision is the 0.2.0 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.
+
+## Release process
+
+Publishing runs in `.github/workflows/publish.yml` on a pushed `v*` tag, using npm
+[trusted publishing](https://docs.npmjs.com/trusted-publishers): the job exchanges its OIDC token for a
+short-lived publish credential, so the repository holds no `NPM_TOKEN`, and npm attaches a provenance
+attestation automatically because the repository is public.
+
+**The first version is published from the CLI**, because a package that does not exist yet cannot have
+a trusted publisher configured from a workflow (npm also offers a *pending publisher* for that case):
+
+```bash
+npm login                 # or refresh the token in ~/.npmrc
+npm publish --access public        # scoped: --access public is required
+```
+
+Then **configure the publisher once** at <https://www.npmjs.com/package/@dumbmice/pi-todo-loop/access>:
+
+| Field | Value |
+|---|---|
+| Provider | GitHub Actions |
+| Organization or user | `DumbMice` |
+| Repository | `pi-todo-loop` |
+| Workflow filename | `publish.yml` |
+| Environment | leave empty |
+
+Or from the CLI (npm >= 11.15):
+
+```bash
+npx npm@latest trust github @dumbmice/pi-todo-loop \
+  --file publish.yml --repo DumbMice/pi-todo-loop --allow-publish
+npx npm@latest trust list @dumbmice/pi-todo-loop
+```
+
+The workflow must keep that filename: npm pins the publisher to it. It skips the publish when the tag's
+version already exists on npm, so the manual first release and a re-run of the same tag both work; the
+GitHub release is still created. It runs `npm ci`, the suite, the
+typecheck and `npm run pack:check`, refuses to publish when the tag and `package.json` disagree, packs
+the tarball and asserts the packed manifest still declares `pi.extensions`, then publishes and creates
+the GitHub release from the matching `CHANGELOG.md` section. It has no inputs: a manual `workflow_dispatch` is a
+`dry_run` — it verifies everything and publishes nothing.
+
+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"
+git add -A
+git commit -m "chore: release v$VERSION"
+git tag -a "v$VERSION" -m "v$VERSION"
+git push origin main --follow-tags
+```
+
+For the **first** release only: `npm publish --access public` before pushing the tag. Push the tag
+anyway — the workflow notices the version already exists, skips the upload, and creates the GitHub
+release.
+
+`--follow-tags` pushes only **annotated** tags, which is why the recipe uses `git tag -a`. A pushed tag
+starts the publish; nothing else does.
+
+Until the trusted publisher is configured, `publish.yml` fails at the publish step by design (the OIDC
+exchange is rejected) — and that is the safe failure: the checks still run, nothing is uploaded.
+## Commits and security
+
+- Commits follow Conventional Commits (`feat:`, `fix:`, `docs:`, `ci:`, `chore:`); release commits are
+  `chore: release vX.Y.Z`.
+- Style: tabs and double quotes, no formatter or linter in the repository. Do not reformat untouched
+  lines.
+- Report vulnerabilities through GitHub's private advisory form (Security → Report a vulnerability),
+  not a public issue.
+- Contributions are accepted under the MIT license (see [LICENSE](LICENSE)).

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+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.1.0] - 2026-11-04
+
+Initial release.
+
+### Added
+
+- `turn_end` continuation while a todo list has open tasks — anything not `completed` or
+  `deleted` — with a per-human-message round cap (`maxRounds`, default 12) and a
+  no-progress strike budget (`maxStrikes`, default 2). Only a settle spends a round: a turn
+  that ended in a tool call already causes pi's next request and costs nothing — but it clears a
+  pending strike, because it is work. A stop keeps the counters: only a new human message starts a
+  new budget.
+- Per-request injection of the authoritative open-task list through the `context` hook,
+  never persisted, closing the post-compaction context hole
+  ([rpiv-mono#222](https://github.com/juicesharp/rpiv-mono/issues/222)) and the "model
+  never calls the todo tool's `list` action" failure ([rpiv-mono#159](https://github.com/juicesharp/rpiv-mono/issues/159)).
+- Hidden continuation marker (`custom_message`, `display: false`, constant 21-character body
+  `<todo_loop_continue/>`, ~200 bytes as a session entry). Markers are kept in history: they sit
+  between assistant turns and are what keeps the conversation alternating. A marker at the tail is
+  replaced by the state block, so a request never ends on two user-role messages.
+- Task state read from `rpiv-todo-state` custom entries with a `todo` toolResult
+  `details.tasks` fallback, the newer of the two winning; never throws inside a turn
+  boundary, and a task with an unusable id falls back to its position instead of vanishing.
+- `/todoloop` command: `status`, `pause`, `resume`, `reset`.
+- Kill switch: `~/.pi/agent/todo-loop-off` or `.pi/todo-loop-off`.
+- Config at `~/.pi/agent/todo-loop.json`; invalid values fall back to defaults, and numbers are
+  clamped (`maxRounds` ≤ 1000, `maxStrikes` ≤ 100, `maxInjectedTasks` ≤ 50).
+- The documentation is split: `README.md` is a user-facing page (what it does, quick start, one example,
+  configuration, commands, troubleshooting, uninstall), and `docs/behaviour.md` holds the mechanics it
+  used to inline — marker lifetime, role alternation, counter semantics, reason strings, scope and cost.
+- `scripts/pack-json.mjs` normalises `npm pack --json`, whose shape differs between npm 10
+  (array) and npm 11 (object keyed by package name); the publish workflow upgrades npm, so
+  both are exercised.
+- Tests, runnable with no dependencies: decision policy, state reader, injection renderer, config
+  loader, the pi-facing hooks through a stub `pi`, a captured real branch, and documentation tests
+  that pin the tested-version table, the invariant map, the reason table, the configuration table and
+  README link targets.
+- `test/state-machine.test.ts`: the counters as a table of event sequences in pi's own vocabulary
+  (`settle`, `tool`, `edit`, `human`, pause/resume/reset, error/abort, kill switch), asserting
+  continuations, markers, rounds, strikes, the `/todoloop` reason and header at once. Re-introducing any
+  of the three historical budget defects fails it.
+- The continuation marker's constant body states the instruction ("Continue with the open todo
+  tasks…") instead of a self-closing tag, so `injectState: false` no longer continues with no
+  instruction at all, and a marker left in history is self-explanatory.
+- A list that goes open → closed in a turn whose only tool results were `todo` is announced once: the
+  loop's success state and its failure state are the same observable.
+- A stale-list burn now says so: the round-cap reason appends `, list unchanged for N settles`.
+- Task text is sanitised before it enters a request — subject, `activeForm` **and `status`**: every
+  Unicode line terminator flattens, `<` is escaped, controls/bidi/zero-width and unpaired surrogates are
+  dropped, and labels truncate by code point, so a task subject cannot close the injection tag or forge a directive. Verified against a
+  crafted subject that closed the tag and inserted a `SYSTEM:` line — the structure broke before the
+  fix and the model refused both times.
+- `.github/workflows/publish.yml`: tag-triggered publish through npm Trusted Publishing (OIDC, no
+  `NPM_TOKEN`, automatic provenance), gated on the suite, the typecheck, `pack:check`, a tag/version
+  match and a packed-manifest assertion; creates the GitHub release from the CHANGELOG section.
+- `scripts/check-pack.mjs` as `npm run pack:check`: asserts the published tarball really contains the
+  entry point, sources, docs, licence and `tsconfig.json`, and that no dev-only path (`test/`,
+  `.github/`) leaks into it (`npm pack --dry-run` exits 0 otherwise).
+
+[0.1.0]: https://github.com/DumbMice/pi-todo-loop/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,4 @@
+# Contributing
+
+See [AGENTS.md](AGENTS.md) for the repository layout, tests, design invariants, documentation
+conventions and release process.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DumbMice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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>.