@sigrun/todo 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [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.2] - 2026-11-05
+### Fixed
+- The published 0.1.1 could not load: `src/panel.ts` imported the host's
+  block builders (`@sigrun/sigrun/blocks`) at RUNTIME, and an extension
+  installed from the registry cannot resolve the host package — it is the
+  host, not a dependency. The panel tree is now built as a plain object
+  (`{ v: 1, root: … }`) with type-only imports from `@sigrun/shared/blocks`,
+  matching `sigrun-escalations`. The tree is unchanged in content and
+  still validates against the host's `validateTree`.
+
+## [0.1.1] - 2026-11-04
+### Added
+- The todo extension: an agent-kept task list with a read-only
+  per-conversation Todos panel in the webui.
+- The `todo` tool (model-only): create, update, delete, clear, list, and get,
+  with the full post-change snapshot carried on every state-changing result
+  for transcript replay.
+- The freshness checks: an end-of-turn check that asks the agent to account
+  for open items (completed, deleted with a note, or kept open with a note),
+  and a mid-run reminder every `reminderRounds` work rounds (default 6).
+- The Todos panel: open items with an in-flight spinner and `activeForm`
+  label, completed items visible and greyed, and a `done/total` line.
+  Deleted items are tombstones — never shown, never counted.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+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,56 @@
-# Temporary Holding Version
+# @sigrun/todo
 
-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.
+An agent-kept task list for [sigrun](https://github.com/sigrun-ai/sigrun).
+The agent owns the list through its `todo` tool; the webui shows it read-only
+in the conversation's right panel, updated live as the agent works.
+
+## Install
+
+Add the extension to `extensions[]` in the sigrun settings file and restart:
+
+```json
+{
+  "extensions": ["@sigrun/todo"]
+}
+```
+
+(a git source — `git:host/path[@ref]` — works too; the repo's committed
+`dist/` is what git-source installs load.)
+
+Until `@sigrun/todo` is published, install from a local path pointing at the
+BUILT entry — `"/path/to/sigrun-todo/dist/index.js"` in `extensions[]` —
+because the loader rejects a bare directory path (`Directory import … is not
+supported`).
+
+## What you get
+
+- **The `todo` tool** (model-only): one call per unit of work —
+  `create`/`update`/`delete`, `in_progress` when the agent starts an item,
+  `completed` when it is done.
+- **The Todos panel** in the conversation's right panel: the full list in
+  id order, with a spinner and the agent's `activeForm` label on the item
+  in flight, completed items greyed (`neutral`) but visible, and a
+  `done/total` line.
+  Deleted items are tombstones — they never appear and do not count.
+- **The freshness checks.** The list belongs to the work, and the extension
+  nudges the agent to keep it current:
+  - *End-of-turn check*: when a run ends having done tool rounds since it
+    last touched the list (or since the run started, if it never did) while
+    items are still open, the run continues once with a check message.
+  - *Mid-run reminder*: every `reminderRounds` work rounds without a `todo`
+    call, a one-request reminder lists the open items.
+  - The check always offers three honest answers — mark it completed, delete
+    it as obsolete, or keep it open with a note saying why; the checks never
+    push a model to fabricate progress.
+
+## Settings
+
+`reminderRounds` — rounds between mid-run reminders (default `6`). There is
+no settings section in v1: edit the extension's settings object through the
+**Extensions** settings raw-JSON editor, e.g. `{ "reminderRounds": 3 }`.
+
+## Known limits
+
+- The TUI does not show extension panels yet — the list is webui-only there;
+  the tool, section, and freshness checks work in every channel.
+- The panel is read-only by design: the agent owns the list.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,30 @@
+# Third-party notices
+
+## rpiv-todo
+
+- <https://github.com/juicesharp/rpiv-todo>
+- `src/types.ts`, `src/state.ts` and `src/graph.ts` are ported from
+  `@juicesharp/rpiv-todo` 2.15.0 (`state/state-reducer.ts`,
+  `state/task-graph.ts`, `state/invariants.ts`, `tool/types.ts`).
+
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+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/dist/freshness.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Freshness analysis: a pure decision table over the request's message array.
+ * No I/O, no state — Task 8's hooks call it with `request.messages` and act on
+ * the answer.
+ *
+ * Two knobs, two different jobs:
+ *
+ * - {@link shouldCheck} — the end-of-turn check. The agent is finishing a run
+ *   it wrote nothing to the list in; asking once is the honest nudge.
+ * - {@link shouldRemind} — the mid-run cadence, every `k` work rounds, so a
+ *   long run does not drift away from the list silently.
+ *
+ * The rules are shaped around the spec's anti-goal: never nag a model into
+ * fabricating progress. So the unit is a ROUND (an assistant message that
+ * called a tool — prose is not work), a run ends at the last human turn (a new
+ * human message is a new intention), and {@link checkText} always offers the
+ * third answer: keep the item open and say why.
+ */
+import type { Message } from "@earendil-works/pi-ai";
+import type { Task, TodoState } from "./types.js";
+/** The check's first token. It doubles as the "this is not a human turn" signal. */
+export declare const TODO_CHECK_MARKER = "[todo check]";
+/**
+ * What the current request's transcript says about freshness:
+ *
+ * - `offered` — the tool set this request leaves in force contains `todo`.
+ *   A turn without the tool cannot be nagged: it has no way to answer.
+ * - `roundsSinceTouch` — work rounds since the later of the run start and the
+ *   last round that called `todo`. A `todo` call in the last round is `0`.
+ * - `lastUserIsCheck` — the run is a continuation of our own check, so it must
+ *   not trigger the next one.
+ */
+export interface RunView {
+    offered: boolean;
+    roundsSinceTouch: number;
+    lastUserIsCheck: boolean;
+}
+/** Every item that still needs work, in id order. Deleted tombstones stay out. */
+export declare function openItems(state: TodoState): Task[];
+/**
+ * Read the request's messages into a {@link RunView}.
+ *
+ * The run starts after the last `user` message; with no user message at all the
+ * whole array is the run, which is what a multi-turn transcript with the input
+ * outside the list looks like.
+ */
+export declare function analyze(messages: readonly Message[]): RunView;
+/**
+ * Whether to ask, at the end of a run, that each open item be resolved. Skipped
+ * for the check's own continuation, or the check would answer itself forever.
+ */
+export declare function shouldCheck(view: RunView, state: TodoState): boolean;
+/** Whether the mid-run cadence wants its every-`k`-rounds reminder. */
+export declare function shouldRemind(view: RunView, state: TodoState, k: number): boolean;
+/**
+ * The end-of-run check, appended as an entry. It names its author because a
+ * model that reads it as a human request would answer the human instead of the
+ * list; and it spells out all three honest answers, because a check offering
+ * only "completed" pushes a model to close what is not done.
+ */
+export declare function checkText(open: readonly Task[]): string;
+/**
+ * The mid-run reminder: the count and the items, short enough to leave room for
+ * the work it interrupts. Reminders only fire with open items, so the list is
+ * never empty here.
+ */
+export declare function reminderText(state: TodoState): string;

package/dist/freshness.js

@@ -0,0 +1,135 @@
+/**
+ * Freshness analysis: a pure decision table over the request's message array.
+ * No I/O, no state — Task 8's hooks call it with `request.messages` and act on
+ * the answer.
+ *
+ * Two knobs, two different jobs:
+ *
+ * - {@link shouldCheck} — the end-of-turn check. The agent is finishing a run
+ *   it wrote nothing to the list in; asking once is the honest nudge.
+ * - {@link shouldRemind} — the mid-run cadence, every `k` work rounds, so a
+ *   long run does not drift away from the list silently.
+ *
+ * The rules are shaped around the spec's anti-goal: never nag a model into
+ * fabricating progress. So the unit is a ROUND (an assistant message that
+ * called a tool — prose is not work), a run ends at the last human turn (a new
+ * human message is a new intention), and {@link checkText} always offers the
+ * third answer: keep the item open and say why.
+ */
+import { getCurrentTools } from "@earendil-works/pi-ai/utils/transcript";
+/** The check's first token. It doubles as the "this is not a human turn" signal. */
+export const TODO_CHECK_MARKER = "[todo check]";
+/** The tool whose calls mark a round as a "touch" of the list. */
+const TODO_TOOL = "todo";
+/** Every item that still needs work, in id order. Deleted tombstones stay out. */
+export function openItems(state) {
+    return state.tasks
+        .filter((task) => task.status === "pending" || task.status === "in_progress")
+        .sort((left, right) => left.id - right.id);
+}
+/** Index of the last `user` message, or `-1` when the run has no human turn. */
+function lastUserIndex(messages) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        if (messages[index]?.role === "user")
+            return index;
+    }
+    return -1;
+}
+/** The first text part of a human turn; `undefined` for an image-only turn. */
+function firstText(content) {
+    if (typeof content === "string")
+        return content;
+    for (const part of content) {
+        if (part.type === "text")
+            return part.text;
+    }
+    return undefined;
+}
+/** A round is work: an assistant message that called at least one tool. */
+function isRound(message) {
+    return message.role === "assistant" && message.content.some((block) => block.type === "toolCall");
+}
+/** Whether this round called `todo` — a read counts: it is the agent touching the list. */
+function touchesList(message) {
+    return message.content.some((block) => block.type === "toolCall" && block.name === TODO_TOOL);
+}
+/** Whether the request's current tool set includes `todo`. */
+function isOffered(messages) {
+    return getCurrentTools(messages).some((tool) => tool.name === TODO_TOOL);
+}
+/**
+ * Read the request's messages into a {@link RunView}.
+ *
+ * The run starts after the last `user` message; with no user message at all the
+ * whole array is the run, which is what a multi-turn transcript with the input
+ * outside the list looks like.
+ */
+export function analyze(messages) {
+    const userIndex = lastUserIndex(messages);
+    const userMessage = userIndex === -1 ? undefined : messages[userIndex];
+    const lastUserIsCheck = userMessage?.role === "user" &&
+        (firstText(userMessage.content)?.startsWith(TODO_CHECK_MARKER) ?? false);
+    let rounds = 0;
+    let lastTouch = -1;
+    for (const message of messages.slice(userIndex + 1)) {
+        if (!isRound(message))
+            continue;
+        if (touchesList(message))
+            lastTouch = rounds;
+        rounds += 1;
+    }
+    return {
+        offered: isOffered(messages),
+        roundsSinceTouch: rounds - (lastTouch + 1),
+        lastUserIsCheck,
+    };
+}
+/**
+ * Whether to ask, at the end of a run, that each open item be resolved. Skipped
+ * for the check's own continuation, or the check would answer itself forever.
+ */
+export function shouldCheck(view, state) {
+    return (view.offered &&
+        openItems(state).length > 0 &&
+        !view.lastUserIsCheck &&
+        view.roundsSinceTouch > 0);
+}
+/** Whether the mid-run cadence wants its every-`k`-rounds reminder. */
+export function shouldRemind(view, state, k) {
+    return (view.offered &&
+        openItems(state).length > 0 &&
+        view.roundsSinceTouch > 0 &&
+        view.roundsSinceTouch % k === 0);
+}
+/** `#2 Write tests (in_progress)` — the raw status token, not prose. */
+function itemLine(task) {
+    return `#${task.id} ${task.subject} (${task.status})`;
+}
+/**
+ * The end-of-run check, appended as an entry. It names its author because a
+ * model that reads it as a human request would answer the human instead of the
+ * list; and it spells out all three honest answers, because a check offering
+ * only "completed" pushes a model to close what is not done.
+ */
+export function checkText(open) {
+    const items = open.map((task) => `- ${itemLine(task)}`).join("\n");
+    return [
+        `${TODO_CHECK_MARKER} This is an automated check from the \`todo\` extension, not a message from the user.`,
+        "",
+        "These items are still open:",
+        items,
+        "",
+        "Make one `todo` call per item: mark it completed, delete it with a note if it no longer applies, or update it with a note saying why it stays open.",
+    ].join("\n");
+}
+/**
+ * The mid-run reminder: the count and the items, short enough to leave room for
+ * the work it interrupts. Reminders only fire with open items, so the list is
+ * never empty here.
+ */
+export function reminderText(state) {
+    const open = openItems(state);
+    const count = open.length === 1 ? "1 open item is" : `${open.length} open items are`;
+    const paragraph = `Reminder from the \`todo\` extension: ${count} still on the list. Keep it current as you work.`;
+    return [paragraph, "", ...open.map((task) => `- ${itemLine(task)}`)].join("\n");
+}

package/dist/graph.d.ts

@@ -0,0 +1,9 @@
+import type { Task } from "./types.js";
+/**
+ * Detect whether merging `newBlockedBy` into `taskId`'s `blockedBy` set would
+ * introduce a cycle in the dependency graph (ported from rpiv-todo, MIT).
+ *
+ * Pure of module state: takes the existing task list and the proposed additions
+ * explicitly so the reducer can ask "would this update cycle?" without writing.
+ */
+export declare function detectCycle(tasks: readonly Task[], taskId: number, newBlockedBy: readonly number[]): boolean;

package/dist/graph.js

@@ -0,0 +1,40 @@
+/**
+ * Detect whether merging `newBlockedBy` into `taskId`'s `blockedBy` set would
+ * introduce a cycle in the dependency graph (ported from rpiv-todo, MIT).
+ *
+ * Pure of module state: takes the existing task list and the proposed additions
+ * explicitly so the reducer can ask "would this update cycle?" without writing.
+ */
+export function detectCycle(tasks, taskId, newBlockedBy) {
+    const edges = new Map();
+    for (const task of tasks) {
+        if (task.id === taskId) {
+            const merged = new Set([...(task.blockedBy ?? []), ...newBlockedBy]);
+            edges.set(task.id, [...merged]);
+        }
+        else {
+            edges.set(task.id, task.blockedBy ? [...task.blockedBy] : []);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const hasCycleFrom = (node) => {
+        if (visiting.has(node))
+            return true;
+        if (visited.has(node))
+            return false;
+        visiting.add(node);
+        for (const blocked of edges.get(node) ?? []) {
+            if (hasCycleFrom(blocked))
+                return true;
+        }
+        visiting.delete(node);
+        visited.add(node);
+        return false;
+    };
+    for (const node of edges.keys()) {
+        if (hasCycleFrom(node))
+            return true;
+    }
+    return false;
+}

package/dist/hooks.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Generation hooks: the freshness policy (Task 7) wired into a run.
+ *
+ * Three handlers, three jobs:
+ *
+ * - `afterTools` ends each round: a round that changed the list makes the
+ *   log's cache entry dirty, and `settle` dropping it reports `true` — the
+ *   signal to refresh whatever panel is open (`onChanged`).
+ * - `beforeRequest` runs before every request attempt. It analyzes the
+ *   request's messages (the only place the current tool list exists) and
+ *   stashes the {@link RunView} for `onYield`, and appends the mid-run
+ *   reminder to the messages it returns — that request only, never a
+ *   transcript entry.
+ * - `onYield` fires the end-of-turn check: read AND DELETE the stashed view
+ *   (memory hygiene — one entry per conversation, dropped on every yield
+ *   whether or not a continuation is returned, since the view is otherwise
+ *   never re-read for that run), and when {@link shouldCheck} holds,
+ *   continue the run with the check message.
+ *
+ * Once-per-run needs no state of its own: after the check's continuation,
+ * the check message is the run's last user message, so `lastUserIsCheck`
+ * holds for the rest of the run — even after more work rounds. `api.memo`
+ * must not be used instead: it is per generation task and does not survive
+ * the handover to the successor generation.
+ *
+ * Error isolation is pi-durable's job (a throwing hook is reported as
+ * `extension_error`), so these handlers carry no try/catch of their own.
+ */
+import { type ConversationId, type HookRegistration } from "@earendil-works/pi-durable";
+import type { TodoLog } from "./log.js";
+export interface TodoHooksDeps {
+    readonly log: TodoLog;
+    /** The reminder cadence `k` (rounds), read per request so settings changes apply. */
+    readonly reminderRounds: () => Promise<number>;
+    /** The panel's cue that the committed list changed (after a `todo` round). */
+    readonly onChanged: (conversationId: ConversationId) => void;
+}
+export declare function createTodoHooks(deps: TodoHooksDeps): HookRegistration;

package/dist/hooks.js

@@ -0,0 +1,65 @@
+/**
+ * Generation hooks: the freshness policy (Task 7) wired into a run.
+ *
+ * Three handlers, three jobs:
+ *
+ * - `afterTools` ends each round: a round that changed the list makes the
+ *   log's cache entry dirty, and `settle` dropping it reports `true` — the
+ *   signal to refresh whatever panel is open (`onChanged`).
+ * - `beforeRequest` runs before every request attempt. It analyzes the
+ *   request's messages (the only place the current tool list exists) and
+ *   stashes the {@link RunView} for `onYield`, and appends the mid-run
+ *   reminder to the messages it returns — that request only, never a
+ *   transcript entry.
+ * - `onYield` fires the end-of-turn check: read AND DELETE the stashed view
+ *   (memory hygiene — one entry per conversation, dropped on every yield
+ *   whether or not a continuation is returned, since the view is otherwise
+ *   never re-read for that run), and when {@link shouldCheck} holds,
+ *   continue the run with the check message.
+ *
+ * Once-per-run needs no state of its own: after the check's continuation,
+ * the check message is the run's last user message, so `lastUserIsCheck`
+ * holds for the rest of the run — even after more work rounds. `api.memo`
+ * must not be used instead: it is per generation task and does not survive
+ * the handover to the successor generation.
+ *
+ * Error isolation is pi-durable's job (a throwing hook is reported as
+ * `extension_error`), so these handlers carry no try/catch of their own.
+ */
+import { GenerationTask, hook, } from "@earendil-works/pi-durable";
+import { analyze, checkText, openItems, reminderText, shouldCheck, shouldRemind, } from "./freshness.js";
+export function createTodoHooks(deps) {
+    const { log, reminderRounds, onChanged } = deps;
+    // `beforeRequest` → `onYield` handoff: `onYield` has no tool list, so the
+    // view computed where one exists is stashed per conversation.
+    const views = new Map();
+    return hook(GenerationTask, {
+        afterTools(_assistant, _results, api) {
+            if (log.settle(api.conversationId))
+                onChanged(api.conversationId);
+        },
+        async beforeRequest(request, api) {
+            const view = analyze(request.messages);
+            views.set(api.conversationId, view);
+            const state = await log.get(api.conversationId);
+            if (!shouldRemind(view, state, await reminderRounds()))
+                return undefined;
+            const reminder = {
+                role: "user",
+                content: [{ type: "text", text: reminderText(state) }],
+                timestamp: Date.now(),
+            };
+            return { messages: [...request.messages, reminder] };
+        },
+        async onYield(_answer, api) {
+            const view = views.get(api.conversationId);
+            views.delete(api.conversationId);
+            if (view === undefined)
+                return undefined;
+            const state = await log.get(api.conversationId);
+            if (!shouldCheck(view, state))
+                return undefined;
+            return { continue: [{ type: "text", text: checkText(openItems(state)) }] };
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The todo extension factory (Task 9): one {@link TodoLog} in front of the
+ * transcript, shared by the tool, the hooks, and the panel, with one
+ * `onChanged` notifying the panel's canonical instance key.
+ *
+ * The factory declares ONE parameter so the loader passes the host in
+ * (`factory.length > 0` gates the host argument); a defaulted first
+ * parameter would swallow it instead.
+ */
+import type { SigrunExtensionResult, SigrunHost } from "@sigrun/sigrun/extension";
+/**
+ * The todo extension: an agent-kept task list with a per-conversation panel.
+ * The required host parameter keeps the factory at arity one for the loader.
+ */
+export default function createTodo(host: SigrunHost): SigrunExtensionResult;

package/dist/index.js

@@ -0,0 +1,62 @@
+/**
+ * The todo extension factory (Task 9): one {@link TodoLog} in front of the
+ * transcript, shared by the tool, the hooks, and the panel, with one
+ * `onChanged` notifying the panel's canonical instance key.
+ *
+ * The factory declares ONE parameter so the loader passes the host in
+ * (`factory.length > 0` gates the host argument); a defaulted first
+ * parameter would swallow it instead.
+ */
+import { defineExtension } from "@earendil-works/pi-durable";
+import { createTodoHooks } from "./hooks.js";
+import { TodoLog, hostEntryReader } from "./log.js";
+import { createTodoPanel, panelKey } from "./panel.js";
+import { todoSection } from "./section.js";
+import { createTodoTool } from "./tool.js";
+/** The default mid-run reminder cadence (rounds between reminders). */
+const DEFAULT_REMINDER_ROUNDS = 6;
+/**
+ * The todo extension: an agent-kept task list with a per-conversation panel.
+ * The required host parameter keeps the factory at arity one for the loader.
+ */
+export default function createTodo(host) {
+    // ONE log: the tool's mutations, the hooks' freshness reads, and the
+    // panel's renders must see the same cache so `settle` re-reads the
+    // transcript exactly once per round.
+    const log = new TodoLog(hostEntryReader(host));
+    const onChanged = (id) => {
+        host.surfaces.changed("todos", panelKey(id));
+    };
+    const deps = { log, onChanged };
+    return {
+        extension: defineExtension({
+            name: "todo",
+            tools: [createTodoTool(deps)],
+            sections: [todoSection],
+            hooks: [
+                createTodoHooks({
+                    ...deps,
+                    // Read PER USE so an edit to the extension's settings applies
+                    // on the next request, without a reload. A positive integer is
+                    // the cadence; anything else is the default.
+                    reminderRounds: async () => {
+                        const settings = (await host.stores.settings.get());
+                        const value = settings?.reminderRounds;
+                        return typeof value === "number" && Number.isInteger(value) && value > 0
+                            ? value
+                            : DEFAULT_REMINDER_ROUNDS;
+                    },
+                }),
+            ],
+        }),
+        surfaces: { panels: [createTodoPanel({ host, log })] },
+        runSettled: (event) => {
+            // Settle at RUN end, not round end: `afterTools` never runs on an
+            // aborted round, so this is the only notification path that always
+            // fires. A dirty entry means the round's change is in the
+            // transcript; a clean one means nothing changed.
+            if (log.settle(event.conversationId))
+                onChanged(event.conversationId);
+        },
+    };
+}

package/dist/log.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Transcript replay + per-conversation cache for `@sigrun/todo`.
+ *
+ * The transcript is the source of truth: every state-changing `todo` call
+ * returns the full post-change snapshot in its tool-result `details`, so the
+ * newest such snapshot in the fork-aware history IS the list. {@link replay}
+ * reads that snapshot; {@link TodoLog} caches it per conversation so a tool
+ * round does not re-scan the history between its own calls.
+ *
+ * The cache deliberately runs ahead of the transcript between a `todo` call
+ * and the round settling: an aborted call's change is uncommitted, and
+ * {@link TodoLog.settle} (called when the round ends) forgets the dirty
+ * entry so the next {@link TodoLog.get} re-reads the transcript without it.
+ */
+import type { ConversationId, EntryRecord } from "@earendil-works/pi-durable";
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+import { type Op } from "./state.js";
+import { type TodoState } from "./types.js";
+/**
+ * A fork-aware, newest-first read of one conversation's transcript. The host
+ * shape is {@link hostEntryReader}; tests drive arrays directly.
+ */
+export type EntryReader = (conversationId: ConversationId) => AsyncIterable<EntryRecord>;
+/**
+ * The {@link EntryReader} over a sigrun host's fork-aware transcript read,
+ * paging `host.conversations.entries` newest-first until exhausted.
+ */
+export declare function hostEntryReader(host: Pick<SigrunHost, "conversations">): EntryReader;
+/**
+ * The todo list of one conversation: the newest committed `todo` snapshot in
+ * its fork-aware history. Walks newest→oldest; a `pi.reset` entry ends the
+ * walk (history before the reset is not this list's history); `pi.compaction`
+ * and everything else is walked past. No snapshot → {@link EMPTY_STATE}.
+ */
+export declare function replay(read: EntryReader, conversationId: ConversationId): Promise<TodoState>;
+/**
+ * The per-conversation todo cache in front of the transcript.
+ *
+ * `get` seeds the cache from the transcript once per conversation;
+ * concurrent callers share ONE seeding promise (the transcript is scanned
+ * once no matter how many of a round's tool calls race). `mutate` awaits
+ * that seed, then reads-applies-writes synchronously — the NO-`await`
+ * window between the read and the write is what serializes parallel calls:
+ * no two mutations can observe the same state. A mutation whose op changes
+ * state ({@link changesState}) marks the entry dirty.
+ *
+ * `settle` ends a round: a dirty entry is dropped (the transcript either
+ * holds its snapshot by then or the call was aborted, in which case the
+ * uncommitted change must disappear) and reports `true`; a clean entry is
+ * kept and reports `false`. `forget` drops the entry unconditionally.
+ */
+export declare class TodoLog {
+    #private;
+    constructor(read: EntryReader);
+    /** The conversation's current state, seeding from the transcript once. */
+    get(id: ConversationId): Promise<TodoState>;
+    /**
+     * Apply `f` to the conversation's current state. Serialized with every
+     * other `mutate` of this conversation: after the seed resolves, the
+     * read-apply-write below contains no `await`, so it is atomic.
+     */
+    mutate(id: ConversationId, f: (state: TodoState) => {
+        state: TodoState;
+        op: Op;
+    }): Promise<{
+        state: TodoState;
+        op: Op;
+    }>;
+    /**
+     * End the conversation's round: a dirty entry is dropped (return `true`)
+     * so the next `get` re-reads the transcript — the committed snapshot, or
+     * the state without an aborted call's uncommitted change. Clean → `false`.
+     */
+    settle(id: ConversationId): boolean;
+    /** Drop the conversation's cache entry; the next `get` re-seeds. */
+    forget(id: ConversationId): void;
+}