@xynogen/pix-todo 0.1.9 → 0.1.12

package/README.md

@@ -6,6 +6,22 @@ Pi tool — durable execution checklist (`todo`).
 
 Registers the `todo` tool, which gives the agent a persistent task checklist that survives context compaction and session restore. The checklist is seeded by the model via the `set` action and tracks items through four statuses: `pending` (○), `in_progress` (◐), `done` (●), and `blocked` (⊘). State is persisted via Pi's `appendEntry("todo-state")` so the agent can recover its position after long runs or compaction events. The agent calls `todo(action:"list")` to resume where it left off. Actions: `list`, `set`, `add`, `update`, `clear`.
 
+## Auto-collapse
+
+The checklist card auto-collapses after a configurable delay (default 10 seconds, previously hardcoded). The delay and the per-tool toggle are read from `~/.pi/agent/pix.json`:
+
+```jsonc
+{
+  "collapse": {
+    "enabled": true,
+    "delayMs": 10000,
+    "tools": { "todo": true }
+  }
+}
+```
+
+Set `collapse.tools.todo: false` to keep the checklist always expanded. See `@xynogen/pix-data/collapse` for the full API.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-todo",
-	"version": "0.1.9",
+	"version": "0.1.12",
 	"description": "Pi tool — durable execution checklist (todo)",
 	"type": "module",
 	"main": "src/index.ts",

package/src/todo.test.ts

@@ -1,9 +1,5 @@
 import { beforeEach, describe, expect, test } from "bun:test";
-import registerTodo, {
-	renderTodoLines,
-	renderTodoSummaryLine,
-	type TodoItem,
-} from "./todo.ts";
+import registerTodo, { renderTodoLines, renderTodoSummaryLine, type TodoItem } from "./todo.ts";
 
 // registerTodo wraps its body in once(pi, "pix-todo") — a per-instance
 // WeakMap guard that dedupes activation across pix-core + a standalone install.
@@ -40,10 +36,7 @@ function makeHost(
 		  }>)
 		| null = null;
 	const appendCalls: Array<{ type: string; data: unknown }> = [];
-	const handlers: Record<
-		string,
-		Array<(event: unknown, ctx?: unknown) => unknown>
-	> = {};
+	const handlers: Record<string, Array<(event: unknown, ctx?: unknown) => unknown>> = {};
 
 	let capturedRender:
 		| ((
@@ -70,8 +63,13 @@ function makeHost(
 			if (!handlers[ev]) handlers[ev] = [];
 			handlers[ev].push(fn);
 		},
-		async emit(ev: string, event?: unknown, ctx?: unknown) {
-			for (const fn of handlers[ev] ?? []) await fn(event, ctx);
+		async emit(ev: string, event?: unknown, ctx?: unknown): Promise<unknown> {
+			let last: unknown;
+			for (const fn of handlers[ev] ?? []) {
+				const result = await fn(event, ctx);
+				if (result !== undefined) last = result;
+			}
+			return last;
 		},
 	} as never;
 
@@ -93,8 +91,13 @@ function makeHost(
 			return capturedRender;
 		},
 		appendCalls,
-		async emit(ev: string, event?: unknown, ctx?: unknown) {
-			for (const fn of handlers[ev] ?? []) await fn(event, ctx);
+		async emit(ev: string, event?: unknown, ctx?: unknown): Promise<unknown> {
+			let last: unknown;
+			for (const fn of handlers[ev] ?? []) {
+				const result = await fn(event, ctx);
+				if (result !== undefined) last = result;
+			}
+			return last;
 		},
 	};
 }
@@ -122,11 +125,7 @@ describe("todo actions", () => {
 	test("list on empty returns (no todos)", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toBe("(no todos)");
 	});
@@ -134,11 +133,7 @@ describe("todo actions", () => {
 	test("set creates items from newline text", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "set",
 			items: "alpha\nbravo\ncharlie",
@@ -153,11 +148,7 @@ describe("todo actions", () => {
 	test("set creates items from numbered list", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "set",
 			items: "1. alpha\n2. bravo",
@@ -168,11 +159,7 @@ describe("todo actions", () => {
 	test("set creates items from bullet list", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "set",
 			items: "- alpha\n* bravo",
@@ -184,11 +171,7 @@ describe("todo actions", () => {
 	test("set ignores empty lines", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "set",
 			items: "alpha\n\nbravo\n  \ncharlie",
@@ -199,11 +182,7 @@ describe("todo actions", () => {
 	test("set with empty items returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "set", items: "" });
 		expect(result.isError).toBe(true);
 		expect(text(result)).toContain("non-empty");
@@ -212,11 +191,7 @@ describe("todo actions", () => {
 	test("set with only whitespace returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "set", items: "  \n  " });
 		expect(result.isError).toBe(true);
 	});
@@ -224,11 +199,7 @@ describe("todo actions", () => {
 	test("set resets ids on re-set", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "first\nsecond" });
 		const result = await run(host.execute, { action: "set", items: "new" });
 		expect(text(result)).toContain("○ 1. new");
@@ -238,11 +209,7 @@ describe("todo actions", () => {
 	test("add appends items", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		const result = await run(host.execute, {
 			action: "add",
@@ -258,11 +225,7 @@ describe("todo actions", () => {
 	test("add with ids continuing sequence", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "first\nsecond\nthird" });
 		const result = await run(host.execute, { action: "add", items: "fourth" });
 		expect(text(result)).toContain("○ 4. fourth");
@@ -271,11 +234,7 @@ describe("todo actions", () => {
 	test("add with empty items returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "add", items: "" });
 		expect(result.isError).toBe(true);
 		expect(text(result)).toContain("non-empty");
@@ -284,11 +243,7 @@ describe("todo actions", () => {
 	test("update changes status", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha\nbravo" });
 		const result = await run(host.execute, {
 			action: "update",
@@ -304,11 +259,7 @@ describe("todo actions", () => {
 	test("update changes text", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "old name" });
 		const result = await run(host.execute, {
 			action: "update",
@@ -321,11 +272,7 @@ describe("todo actions", () => {
 	test("update changes status and text together", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		const result = await run(host.execute, {
 			action: "update",
@@ -341,11 +288,7 @@ describe("todo actions", () => {
 	test("opening a new in_progress closes the previous one", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "a\nb\nc" });
 		await run(host.execute, { action: "update", id: 1, status: "in_progress" });
 		const result = await run(host.execute, {
@@ -363,11 +306,7 @@ describe("todo actions", () => {
 	test("opening a later item cascade-closes skipped pending items", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "a\nb\nc\nd" });
 		// Jump straight to id 4 without opening 1-3; they should all auto-close.
 		const result = await run(host.execute, {
@@ -386,11 +325,7 @@ describe("todo actions", () => {
 	test("cascade-close leaves a blocked earlier item untouched", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "a\nb\nc" });
 		await run(host.execute, { action: "update", id: 1, status: "blocked" });
 		const result = await run(host.execute, {
@@ -407,11 +342,7 @@ describe("todo actions", () => {
 	test("update unknown id returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "update",
 			id: 999,
@@ -424,11 +355,7 @@ describe("todo actions", () => {
 	test("update without status or text does nothing", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "unchanged" });
 		const result = await run(host.execute, { action: "update", id: 1 });
 		expect(text(result)).toContain("○ 1. unchanged");
@@ -437,11 +364,7 @@ describe("todo actions", () => {
 	test("clear empties list", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha\nbravo" });
 		const result = await run(host.execute, { action: "clear" });
 		expect(text(result)).toContain("Todos cleared");
@@ -453,11 +376,7 @@ describe("todo actions", () => {
 	test("clear resets id counter", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha\nbravo\ncharlie" });
 		await run(host.execute, { action: "clear" });
 		const result = await run(host.execute, { action: "set", items: "new" });
@@ -467,11 +386,7 @@ describe("todo actions", () => {
 	test("unknown action returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "bogus" });
 		expect(result.isError).toBe(true);
 		expect(text(result)).toContain("Unknown action");
@@ -480,11 +395,7 @@ describe("todo actions", () => {
 	test("all status glyphs render correctly", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "a\nb\nc\nd" });
 		// Open id 2 first (cascade-closes nothing earlier we assert on), then set
 		// the others directly so each glyph is exercised without cascade interfering.
@@ -508,11 +419,7 @@ describe("persistence", () => {
 	test("set persists todos", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		host.appendCalls.length = 0;
 		await run(host.execute, { action: "set", items: "alpha\nbravo" });
 		expect(host.appendCalls.length).toBe(1);
@@ -529,11 +436,7 @@ describe("persistence", () => {
 	test("add persists todos", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		host.appendCalls.length = 0;
 		await run(host.execute, { action: "add", items: "bravo" });
@@ -543,11 +446,7 @@ describe("persistence", () => {
 	test("update persists todos", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		host.appendCalls.length = 0;
 		await run(host.execute, { action: "update", id: 1, status: "done" });
@@ -557,11 +456,7 @@ describe("persistence", () => {
 	test("clear persists", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		host.appendCalls.length = 0;
 		await run(host.execute, { action: "clear" });
@@ -590,11 +485,7 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toContain("● 1. restored");
 		expect(text(result)).toContain("Todos 1/1 done");
@@ -612,11 +503,7 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "add", items: "new" });
 		expect(text(result)).toContain("○ 6. new");
 	});
@@ -635,11 +522,7 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "add", items: "next" });
 		expect(text(result)).toContain("○ 8. next");
 	});
@@ -658,11 +541,7 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toContain("○ 1. real");
 	});
@@ -670,11 +549,7 @@ describe("restore", () => {
 	test("no todo-state entries starts empty", async () => {
 		const host = makeHost([{ type: "message", data: "hello" }]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toBe("(no todos)");
 	});
@@ -682,11 +557,7 @@ describe("restore", () => {
 	test("empty entries list starts empty", async () => {
 		const host = makeHost([]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toBe("(no todos)");
 	});
@@ -700,16 +571,139 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toBe("(no todos)");
 	});
 });
 
+// ─── Skip-guard ─────────────────────────────────────────────────────────────────────
+
+describe("skip-guard on marking done", () => {
+	test("warns when marking a later item done with earlier pending items", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc\nd" });
+		// Mark items 1 and 4 done, leaving 2 and 3 pending
+		await run(host.execute, { action: "update", id: 1, status: "done" });
+		const result = await run(host.execute, { action: "update", id: 4, status: "done" });
+		const out = text(result);
+		expect(out).toContain("\u26a0 Earlier items still incomplete");
+		expect(out).toContain("#2 (b)");
+		expect(out).toContain("#3 (c)");
+		expect(out).toContain("Mark each done or blocked before proceeding");
+	});
+
+	test("no warning when all earlier items are done", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc" });
+		await run(host.execute, { action: "update", id: 1, status: "done" });
+		await run(host.execute, { action: "update", id: 2, status: "done" });
+		const result = await run(host.execute, { action: "update", id: 3, status: "done" });
+		expect(text(result)).not.toContain("\u26a0");
+	});
+
+	test("no warning when marking the first item done", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb" });
+		const result = await run(host.execute, { action: "update", id: 1, status: "done" });
+		expect(text(result)).not.toContain("\u26a0");
+	});
+
+	test("no warning when earlier items are blocked (only pending/in_progress trigger)", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc" });
+		await run(host.execute, { action: "update", id: 1, status: "blocked" });
+		await run(host.execute, { action: "update", id: 2, status: "done" });
+		const result = await run(host.execute, { action: "update", id: 3, status: "done" });
+		// blocked is an explicit decision, not incomplete — no warning
+		expect(text(result)).not.toContain("\u26a0");
+	});
+
+	test("warns about in_progress items too (not just pending)", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc" });
+		await run(host.execute, { action: "update", id: 1, status: "in_progress" });
+		// Mark item 3 done while item 1 is still in_progress
+		const result = await run(host.execute, { action: "update", id: 3, status: "done" });
+		const out = text(result);
+		expect(out).toContain("\u26a0");
+		expect(out).toContain("#1 (a)");
+	});
+
+	test("no skip-guard on in_progress (only on done)", async () => {
+		// in_progress uses cascade-close instead, which is different behavior
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc" });
+		const result = await run(host.execute, { action: "update", id: 3, status: "in_progress" });
+		// Should cascade-close, not warn
+		expect(text(result)).not.toContain("\u26a0");
+		expect(text(result)).toContain("\u25cf 1. a"); // cascade-closed to done
+		expect(text(result)).toContain("\u25cf 2. b");
+	});
+});
+
+// ─── Turn-based reminder ────────────────────────────────────────────────────────────
+
+describe("turn-based todo reminder", () => {
+	test("injects reminder every 10 turns when incomplete items exist", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb" });
+
+		// Simulate 10 turns — only the 10th should inject
+		for (let i = 1; i <= 9; i++) {
+			const result = await host.emit("before_agent_start", { systemPrompt: "base" });
+			// before_agent_start returns undefined when no injection
+			expect(result).toBeUndefined();
+		}
+		// 10th turn should inject
+		const result = await host.emit("before_agent_start", { systemPrompt: "base" });
+		expect(result).toBeDefined();
+		const prompt = (result as { systemPrompt: string }).systemPrompt;
+		expect(prompt).toContain("base");
+		expect(prompt).toContain("Todo reminder");
+		expect(prompt).toContain("1. a");
+		expect(prompt).toContain("2. b");
+	});
+
+	test("does not inject when no todos exist", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+
+		for (let i = 1; i <= 10; i++) {
+			const result = await host.emit("before_agent_start", { systemPrompt: "base" });
+			expect(result).toBeUndefined();
+		}
+	});
+
+	test("does not inject when all items are done", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a" });
+		await run(host.execute, { action: "update", id: 1, status: "done" });
+
+		for (let i = 1; i <= 10; i++) {
+			const result = await host.emit("before_agent_start", { systemPrompt: "base" });
+			expect(result).toBeUndefined();
+		}
+	});
+});
+
 describe("renderTodoLines (colored TUI render)", () => {
 	const items: TodoItem[] = [
 		{ id: 1, text: "alpha", status: "done" },
@@ -754,11 +748,7 @@ describe("renderResult snapshot isolation", () => {
 	test("a rendered card keeps its state after todos mutate", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha\nbravo" });
 
 		// Render once with a per-row state bag; snapshot is taken here.
@@ -789,8 +779,6 @@ describe("renderTodoSummaryLine (collapsed one-liner)", () => {
 			{ id: 1, text: "a", status: "done" },
 			{ id: 2, text: "b", status: "pending" },
 		];
-		expect(renderTodoSummaryLine(items, tagTheme)).toBe(
-			"[muted]Todos 1/2 done ✓[/]",
-		);
+		expect(renderTodoSummaryLine(items, tagTheme)).toBe("[muted]Todos 1/2 done ✓[/]");
 	});
 });

package/src/todo.ts

@@ -9,14 +9,65 @@
  * checklist is seeded by the model via the tool's `set` action.
  */
 
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { once } from "./once.ts";
 
-/** Seconds before a todo card collapses to a one-line dim summary. */
-const COLLAPSE_AFTER_SEC = 10;
+// ── Collapse config from ~/.pi/agent/pix.json ────────────────────────────────
+
+interface CollapseConf {
+	enabled: boolean;
+	delaySec: number;
+	tools: Record<string, boolean | undefined>;
+}
+
+const DEFAULT_COLLAPSE: CollapseConf = {
+	enabled: true,
+	delaySec: 10,
+	tools: {},
+};
+
+function readCollapseConfig(): CollapseConf {
+	try {
+		const home = process.env.HOME ?? "";
+		if (!home) return DEFAULT_COLLAPSE;
+		const p = join(home, ".pi/agent", "pix.json");
+		if (!existsSync(p)) return DEFAULT_COLLAPSE;
+		const raw = JSON.parse(readFileSync(p, "utf-8")) as Record<string, unknown>;
+		const c = raw?.collapse as Record<string, unknown> | undefined;
+		if (!c || typeof c !== "object") return DEFAULT_COLLAPSE;
+		return {
+			enabled: typeof c.enabled === "boolean" ? c.enabled : true,
+			delaySec: typeof c.delaySec === "number" && c.delaySec > 0 ? c.delaySec : 10,
+			tools:
+				c.tools && typeof c.tools === "object"
+					? (c.tools as Record<string, boolean | undefined>)
+					: {},
+		};
+	} catch {
+		return DEFAULT_COLLAPSE;
+	}
+}
+
+let collapseConf: CollapseConf | null = null;
+function getCollapseConfig(): CollapseConf {
+	if (!collapseConf) collapseConf = readCollapseConfig();
+	return collapseConf;
+}
+
+function shouldCollapseTodo(): boolean {
+	const c = getCollapseConfig();
+	const perTool = c.tools.todo;
+	return typeof perTool === "boolean" ? perTool : c.enabled;
+}
+
+function collapseDelayMs(): number {
+	return getCollapseConfig().delaySec * 1000;
+}
 
 export type TodoStatus = "pending" | "in_progress" | "done" | "blocked";
 
@@ -47,10 +98,7 @@ export type TodoTheme = {
 };
 
 /** One-line dim summary used once a card has collapsed. */
-export function renderTodoSummaryLine(
-	items: TodoItem[],
-	theme: TodoTheme,
-): string {
+export function renderTodoSummaryLine(items: TodoItem[], theme: TodoTheme): string {
 	if (!items.length) return theme.fg("muted", "(no todos)");
 	const done = items.filter((t) => t.status === "done").length;
 	return theme.fg("muted", `Todos ${done}/${items.length} done ✓`);
@@ -75,6 +123,22 @@ export function renderTodoLines(items: TodoItem[], theme: TodoTheme): string {
 	return `${head}\n${lines.join("\n")}`;
 }
 
+/**
+ * Skip-guard: when marking an item done, check for earlier items still
+ * pending or in_progress. Returns a warning string or "" if none skipped.
+ */
+function buildSkipWarning(items: TodoItem[], targetId: number): string {
+	const skipped = items.filter(
+		(o) => o.id < targetId && (o.status === "pending" || o.status === "in_progress"),
+	);
+	if (skipped.length === 0) return "";
+	const ids = skipped.map((s) => `#${s.id} (${s.text})`).join(", ");
+	return (
+		`\n\n\u26a0 Earlier items still incomplete: ${ids}. ` +
+		"Mark each done or blocked before proceeding."
+	);
+}
+
 const parseItems = (raw: string): string[] =>
 	raw
 		.split("\n")
@@ -93,9 +157,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 		function todoSummary(): string {
 			if (!todos.length) return "(no todos)";
 			const done = todos.filter((t) => t.status === "done").length;
-			const lines = todos.map(
-				(t) => `${TODO_GLYPH[t.status]} ${t.id}. ${t.text}`,
-			);
+			const lines = todos.map((t) => `${TODO_GLYPH[t.status]} ${t.id}. ${t.text}`);
 			return `Todos ${done}/${todos.length} done:\n${lines.join("\n")}`;
 		}
 
@@ -112,6 +174,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 			promptGuidelines: [
 				"When you start executing a multi-step plan in BUILD mode, seed the todo list with `todo(action:'set', items: <plan Implementation Phases>)`.",
 				"Mark each item in_progress before working it via `todo(action:'update', id, status)`; opening one auto-closes every earlier item, so just open the next and skipped steps mark done themselves.",
+				"When marking an item done, the tool checks for earlier incomplete items and warns you — resolve each skipped item (mark done or blocked) before moving on.",
 				"Call `todo(action:'list')` to recover your place after long runs or context compaction.",
 			],
 			parameters: Type.Object({
@@ -127,13 +190,10 @@ export default function registerTodo(pi: ExtensionAPI): void {
 				),
 				items: Type.Optional(
 					Type.String({
-						description:
-							"For set/add: newline-separated or numbered list of todo texts.",
+						description: "For set/add: newline-separated or numbered list of todo texts.",
 					}),
 				),
-				id: Type.Optional(
-					Type.Number({ description: "For update: target todo id." }),
-				),
+				id: Type.Optional(Type.Number({ description: "For update: target todo id." })),
 				status: Type.Optional(
 					Type.Union(
 						[
@@ -161,15 +221,14 @@ export default function registerTodo(pi: ExtensionAPI): void {
 				};
 				if (!state.snapshot) state.snapshot = todos.map((t) => ({ ...t }));
 				// Start the collapse timer once per row; invalidate() triggers rerender.
-				if (!state.collapsed && !state.timer) {
+				// Config-driven: reads from ~/.pi/agent/pix.json collapse section.
+				if (shouldCollapseTodo() && !state.collapsed && !state.timer) {
 					state.timer = setTimeout(() => {
 						state.collapsed = true;
 						context.invalidate();
-					}, COLLAPSE_AFTER_SEC * 1000);
+					}, collapseDelayMs());
 				}
-				const render = state.collapsed
-					? renderTodoSummaryLine
-					: renderTodoLines;
+				const render = state.collapsed ? renderTodoSummaryLine : renderTodoLines;
 				return new Text(render(state.snapshot, theme as TodoTheme), 0, 0);
 			},
 
@@ -205,8 +264,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 					case "add": {
 						const texts = parseItems(params.items ?? "");
 						if (!texts.length) return fail("add requires non-empty `items`.");
-						for (const text of texts)
-							todos.push({ id: nextTodoId++, text, status: "pending" });
+						for (const text of texts) todos.push({ id: nextTodoId++, text, status: "pending" });
 						persistTodos();
 						return ok(todoSummary());
 					}
@@ -214,6 +272,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 					case "update": {
 						const t = todos.find((x) => x.id === params.id);
 						if (!t) return fail(`No todo with id ${params.id}.`);
+						let skipWarning = "";
 						if (params.status) {
 							// Sequential-progress invariant: opening a task means everything
 							// before it is finished. Cascade-close every earlier pending or
@@ -223,15 +282,17 @@ export default function registerTodo(pi: ExtensionAPI): void {
 								for (const other of todos)
 									if (
 										other.id < t.id &&
-										(other.status === "pending" ||
-											other.status === "in_progress")
+										(other.status === "pending" || other.status === "in_progress")
 									)
 										other.status = "done";
+
+							if (params.status === "done") skipWarning = buildSkipWarning(todos, t.id);
+
 							t.status = params.status;
 						}
 						if (params.text) t.text = params.text;
 						persistTodos();
-						return ok(todoSummary());
+						return ok(todoSummary() + skipWarning);
 					}
 
 					case "clear":
@@ -246,6 +307,32 @@ export default function registerTodo(pi: ExtensionAPI): void {
 			},
 		});
 
+		// ── Turn-based reminder ─────────────────────────────────────────────
+		// Every TODO_REMINDER_INTERVAL turns, inject the current todo summary
+		// into the system prompt so the model stays aware of pending work and
+		// can't hand-wave or ignore incomplete items.
+		const TODO_REMINDER_INTERVAL = 10;
+		let todoTurnCount = 0;
+
+		pi.on("before_agent_start", async (event) => {
+			todoTurnCount++;
+			// Only inject when there are active (non-empty) todos
+			if (todos.length === 0) return;
+			// Check if any items are still incomplete
+			const hasIncomplete = todos.some((t) => t.status === "pending" || t.status === "in_progress");
+			if (!hasIncomplete) return;
+			// Fire on every Nth turn
+			if (todoTurnCount % TODO_REMINDER_INTERVAL !== 0) return;
+
+			const reminder =
+				"Todo reminder — incomplete items remain:\n" +
+				todoSummary() +
+				"\nCall `todo(action:'list')` to review, then continue working through pending items.";
+
+			const existing = event.systemPrompt ?? "";
+			return { systemPrompt: existing ? `${existing}\n\n${reminder}` : reminder };
+		});
+
 		// Restore the checklist from session entries so it survives restart.
 		pi.on("session_start", async (_event, ctx) => {
 			const entries = ctx.sessionManager.getEntries() as Array<{
@@ -258,9 +345,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 				.pop();
 			if (Array.isArray(lastTodo?.data?.todos)) {
 				todos = lastTodo.data.todos;
-				nextTodoId =
-					lastTodo.data.nextTodoId ??
-					todos.reduce((m, t) => Math.max(m, t.id + 1), 1);
+				nextTodoId = lastTodo.data.nextTodoId ?? todos.reduce((m, t) => Math.max(m, t.id + 1), 1);
 			}
 		});
 	});