opencode-session-todo 0.2.0 → 0.3.0

package/README.md

@@ -31,4 +31,4 @@ Reload OpenCode and reopen the TUI.
 - **Keep tasks in view** in the sidebar; open `/todos` for the full list.
 - **Own the file** at `.agents/sessions/<session-id>/todo.txt`.
 
-[Usage & permissions](USAGE.md) · [Development & publishing](docs/development.md) · [MIT](LICENSE)
+[MIT](LICENSE)

package/dist/tui.js

@@ -115,6 +115,11 @@ var colorFor = (status, theme) => {
       return theme.text.feedback.error.base;
   }
 };
+var priorityBadge = {
+  high: "(A)",
+  medium: "(B)",
+  low: "(C)"
+};
 var Message = Schema4.Struct({
   message: Schema4.String
 });
@@ -137,16 +142,6 @@ var tui_default = Plugin.define({
         open: true
       }
     });
-    const notify = api.events.on("updated", (event) => {
-      if (event.data.summary === "")
-        return;
-      ctx.ui.toast.show({
-        title: "TODO updated",
-        message: event.data.summary,
-        variant: "info",
-        sessionID: event.data.sessionID
-      });
-    });
     const List = (props) => {
       const [view, setView] = createSignal({
         status: "loading"
@@ -225,127 +220,215 @@ var tui_default = Plugin.define({
         return current.status === "error" ? current.message : undefined;
       };
       const visible = () => Boolean(props.full || snapshot()?.todos.length || error());
-      return _$createComponent(Show, {
+      const Header = () => (() => {
+        var _el$ = _$createElement("box"), _el$3 = _$createElement("box"), _el$4 = _$createElement("text"), _el$5 = _$createElement("b"), _el$7 = _$createElement("span"), _el$8 = _$createTextNode(` (`), _el$0 = _$createTextNode(` remaining)`);
+        _$insertNode(_el$, _el$3);
+        _$setProp(_el$, "flexDirection", "row");
+        _$setProp(_el$, "gap", 1);
+        _$setProp(_el$, "flexShrink", 0);
+        _$setProp(_el$, "onMouseDown", (event) => {
+          if (props.full)
+            return;
+          event.stopPropagation();
+          updateSidebarView((draft) => {
+            draft.open = !draft.open;
+          }).catch((error) => {
+            ctx.ui.toast.show({
+              title: "Todo sidebar",
+              message: `Cannot save expanded state: ${messageFor(error)}`,
+              variant: "error"
+            });
+          });
+        });
+        _$insert(_el$, _$createComponent(Show, {
+          get when() {
+            return !props.full;
+          },
+          get children() {
+            var _el$2 = _$createElement("text");
+            _$insert(_el$2, () => sidebarView.open ? "\u25BC" : "\u25B6");
+            _$effect((_$p) => _$setProp(_el$2, "fg", ctx.theme.text.base, _$p));
+            return _el$2;
+          }
+        }), _el$3);
+        _$insertNode(_el$3, _el$4);
+        _$setProp(_el$3, "flexGrow", 1);
+        _$setProp(_el$3, "flexShrink", 1);
+        _$setProp(_el$3, "minWidth", 0);
+        _$insertNode(_el$4, _el$5);
+        _$insertNode(_el$4, _el$7);
+        _$insertNode(_el$5, _$createTextNode(`TODO`));
+        _$insertNode(_el$7, _el$8);
+        _$insertNode(_el$7, _el$0);
+        _$insert(_el$7, active, _el$0);
+        _$insert(_el$, _$createComponent(Show, {
+          get when() {
+            return _$memo(() => !!props.full)() ? props.onClose : undefined;
+          },
+          children: (onClose) => (() => {
+            var _el$1 = _$createElement("text");
+            _$insertNode(_el$1, _$createTextNode(`\xD7`));
+            _$setProp(_el$1, "flexShrink", 0);
+            _$setProp(_el$1, "selectable", false);
+            _$setProp(_el$1, "onMouseDown", (event) => {
+              event.stopPropagation();
+              onClose()();
+            });
+            _$effect((_$p) => _$setProp(_el$1, "fg", ctx.theme.text.muted, _$p));
+            return _el$1;
+          })()
+        }), null);
+        _$effect((_p$) => {
+          var _v$ = props.full ? 1 : 0, _v$2 = ctx.theme.text.base, _v$3 = {
+            fg: ctx.theme.text.muted
+          };
+          _v$ !== _p$.e && (_p$.e = _$setProp(_el$, "paddingBottom", _v$, _p$.e));
+          _v$2 !== _p$.t && (_p$.t = _$setProp(_el$4, "fg", _v$2, _p$.t));
+          _v$3 !== _p$.a && (_p$.a = _$setProp(_el$7, "style", _v$3, _p$.a));
+          return _p$;
+        }, {
+          e: undefined,
+          t: undefined,
+          a: undefined
+        });
+        return _el$;
+      })();
+      const Body = () => [_$createComponent(Show, {
         get when() {
-          return visible();
+          return error();
         },
         get children() {
-          var _el$ = _$createElement("box"), _el$2 = _$createElement("box"), _el$4 = _$createElement("text"), _el$5 = _$createElement("b"), _el$7 = _$createElement("span"), _el$8 = _$createTextNode(` (`), _el$0 = _$createTextNode(` remaining)`);
-          _$insertNode(_el$, _el$2);
-          _$setProp(_el$, "flexDirection", "column");
-          _$setProp(_el$, "gap", 0);
-          _$setProp(_el$, "paddingTop", 1);
-          _$insertNode(_el$2, _el$4);
-          _$setProp(_el$2, "flexDirection", "row");
-          _$setProp(_el$2, "gap", 1);
-          _$setProp(_el$2, "onMouseDown", (event) => {
-            if (props.full)
-              return;
-            event.stopPropagation();
-            updateSidebarView((draft) => {
-              draft.open = !draft.open;
-            }).catch((error) => {
-              ctx.ui.toast.show({
-                title: "Todo sidebar",
-                message: `Cannot save expanded state: ${messageFor(error)}`,
-                variant: "error"
+          var _el$11 = _$createElement("text"), _el$12 = _$createTextNode(`Cannot read todos: `);
+          _$insertNode(_el$11, _el$12);
+          _$insert(_el$11, error, null);
+          _$effect((_$p) => _$setProp(_el$11, "fg", ctx.theme.text.feedback.error.base, _$p));
+          return _el$11;
+        }
+      }), _$createComponent(Show, {
+        get when() {
+          return _$memo(() => !!(props.full && view().status === "ready"))() && todos().length === 0;
+        },
+        get children() {
+          var _el$13 = _$createElement("text");
+          _$insertNode(_el$13, _$createTextNode(`No todos for this session.`));
+          _$effect((_$p) => _$setProp(_el$13, "fg", ctx.theme.text.muted, _$p));
+          return _el$13;
+        }
+      }), _$createComponent(Show, {
+        get when() {
+          return props.full;
+        },
+        get fallback() {
+          return _$createComponent(For, {
+            get each() {
+              return todos();
+            },
+            children: (todo) => (() => {
+              var _el$18 = _$createElement("text");
+              _$insert(_el$18, () => formatTodo(todo));
+              _$effect((_$p) => _$setProp(_el$18, "fg", colorFor(todo.status, ctx.theme), _$p));
+              return _el$18;
+            })()
+          });
+        },
+        get children() {
+          return _$createComponent(For, {
+            get each() {
+              return todos();
+            },
+            children: (todo) => (() => {
+              var _el$19 = _$createElement("box"), _el$20 = _$createElement("text"), _el$21 = _$createElement("box"), _el$22 = _$createElement("text"), _el$23 = _$createElement("text");
+              _$insertNode(_el$19, _el$20);
+              _$insertNode(_el$19, _el$21);
+              _$insertNode(_el$19, _el$23);
+              _$setProp(_el$19, "flexDirection", "row");
+              _$setProp(_el$19, "gap", 1);
+              _$setProp(_el$20, "width", 3);
+              _$setProp(_el$20, "flexShrink", 0);
+              _$insert(_el$20, () => todoSymbols[todo.status]);
+              _$insertNode(_el$21, _el$22);
+              _$setProp(_el$21, "flexGrow", 1);
+              _$setProp(_el$21, "flexShrink", 1);
+              _$setProp(_el$21, "minWidth", 0);
+              _$setProp(_el$22, "wrapMode", "word");
+              _$insert(_el$22, () => todo.content);
+              _$setProp(_el$23, "width", 3);
+              _$setProp(_el$23, "flexShrink", 0);
+              _$insert(_el$23, () => priorityBadge[todo.priority]);
+              _$effect((_p$) => {
+                var _v$4 = colorFor(todo.status, ctx.theme), _v$5 = colorFor(todo.status, ctx.theme), _v$6 = ctx.theme.text.muted;
+                _v$4 !== _p$.e && (_p$.e = _$setProp(_el$20, "fg", _v$4, _p$.e));
+                _v$5 !== _p$.t && (_p$.t = _$setProp(_el$22, "fg", _v$5, _p$.t));
+                _v$6 !== _p$.a && (_p$.a = _$setProp(_el$23, "fg", _v$6, _p$.a));
+                return _p$;
+              }, {
+                e: undefined,
+                t: undefined,
+                a: undefined
               });
-            });
+              return _el$19;
+            })()
+          });
+        }
+      }), _$createComponent(Show, {
+        get when() {
+          return more();
+        },
+        get children() {
+          var _el$15 = _$createElement("text"), _el$16 = _$createTextNode(`Show all `), _el$17 = _$createTextNode(` todos \u2192`);
+          _$insertNode(_el$15, _el$16);
+          _$insertNode(_el$15, _el$17);
+          _$setProp(_el$15, "onMouseDown", (event) => {
+            event.stopPropagation();
+            ctx.ui.panel.open("session-todo.list");
           });
-          _$insert(_el$2, _$createComponent(Show, {
+          _$insert(_el$15, more, _el$17);
+          _$effect((_$p) => _$setProp(_el$15, "fg", ctx.theme.text.feedback.info.base, _$p));
+          return _el$15;
+        }
+      })];
+      return _$createComponent(Show, {
+        get when() {
+          return visible();
+        },
+        get children() {
+          return _$createComponent(Show, {
             get when() {
-              return !props.full;
+              return props.full;
             },
-            get children() {
-              var _el$3 = _$createElement("text");
-              _$insert(_el$3, () => sidebarView.open ? "\u25BC" : "\u25B6");
-              _$effect((_$p) => _$setProp(_el$3, "fg", ctx.theme.text.base, _$p));
-              return _el$3;
-            }
-          }), _el$4);
-          _$insertNode(_el$4, _el$5);
-          _$insertNode(_el$4, _el$7);
-          _$insertNode(_el$5, _$createTextNode(`TODO`));
-          _$insertNode(_el$7, _el$8);
-          _$insertNode(_el$7, _el$0);
-          _$insert(_el$7, active, _el$0);
-          _$insert(_el$, _$createComponent(Show, {
-            get when() {
-              return props.full || sidebarView.open;
+            get fallback() {
+              return (() => {
+                var _el$26 = _$createElement("box");
+                _$setProp(_el$26, "flexDirection", "column");
+                _$setProp(_el$26, "gap", 0);
+                _$setProp(_el$26, "paddingTop", 1);
+                _$insert(_el$26, _$createComponent(Header, {}), null);
+                _$insert(_el$26, _$createComponent(Show, {
+                  get when() {
+                    return sidebarView.open;
+                  },
+                  get children() {
+                    return _$createComponent(Body, {});
+                  }
+                }), null);
+                return _el$26;
+              })();
             },
             get children() {
-              return [_$createComponent(Show, {
-                get when() {
-                  return props.full;
-                },
-                get children() {
-                  var _el$1 = _$createElement("text");
-                  _$insert(_el$1, () => snapshot()?.path ?? "Loading todo.txt\u2026");
-                  _$effect((_$p) => _$setProp(_el$1, "fg", ctx.theme.text.muted, _$p));
-                  return _el$1;
-                }
-              }), _$createComponent(Show, {
-                get when() {
-                  return error();
-                },
-                get children() {
-                  var _el$10 = _$createElement("text"), _el$11 = _$createTextNode(`Cannot read todos: `);
-                  _$insertNode(_el$10, _el$11);
-                  _$insert(_el$10, error, null);
-                  _$effect((_$p) => _$setProp(_el$10, "fg", ctx.theme.text.feedback.error.base, _$p));
-                  return _el$10;
-                }
-              }), _$createComponent(Show, {
-                get when() {
-                  return _$memo(() => !!(props.full && view().status === "ready"))() && todos().length === 0;
-                },
-                get children() {
-                  var _el$12 = _$createElement("text");
-                  _$insertNode(_el$12, _$createTextNode(`No todos for this session.`));
-                  _$effect((_$p) => _$setProp(_el$12, "fg", ctx.theme.text.muted, _$p));
-                  return _el$12;
-                }
-              }), _$createComponent(For, {
-                get each() {
-                  return todos();
-                },
-                children: (todo) => (() => {
-                  var _el$17 = _$createElement("text");
-                  _$insert(_el$17, () => formatTodo(todo));
-                  _$effect((_$p) => _$setProp(_el$17, "fg", colorFor(todo.status, ctx.theme), _$p));
-                  return _el$17;
-                })()
-              }), _$createComponent(Show, {
-                get when() {
-                  return more();
-                },
-                get children() {
-                  var _el$14 = _$createElement("text"), _el$15 = _$createTextNode(`Show all `), _el$16 = _$createTextNode(` todos \u2192`);
-                  _$insertNode(_el$14, _el$15);
-                  _$insertNode(_el$14, _el$16);
-                  _$setProp(_el$14, "onMouseDown", (event) => {
-                    event.stopPropagation();
-                    ctx.ui.panel.open("session-todo.list");
-                  });
-                  _$insert(_el$14, more, _el$16);
-                  _$effect((_$p) => _$setProp(_el$14, "fg", ctx.theme.text.feedback.info.base, _$p));
-                  return _el$14;
-                }
-              })];
+              var _el$24 = _$createElement("box"), _el$25 = _$createElement("scrollbox");
+              _$insertNode(_el$24, _el$25);
+              _$setProp(_el$24, "flexDirection", "column");
+              _$setProp(_el$24, "flexGrow", 1);
+              _$setProp(_el$24, "minHeight", 0);
+              _$setProp(_el$24, "padding", 1);
+              _$insert(_el$24, _$createComponent(Header, {}), _el$25);
+              _$setProp(_el$25, "flexGrow", 1);
+              _$setProp(_el$25, "flexBasis", 0);
+              _$setProp(_el$25, "minHeight", 0);
+              _$insert(_el$25, _$createComponent(Body, {}));
+              return _el$24;
             }
-          }), null);
-          _$effect((_p$) => {
-            var _v$ = ctx.theme.text.base, _v$2 = {
-              fg: ctx.theme.text.muted
-            };
-            _v$ !== _p$.e && (_p$.e = _$setProp(_el$4, "fg", _v$, _p$.e));
-            _v$2 !== _p$.t && (_p$.t = _$setProp(_el$7, "style", _v$2, _p$.t));
-            return _p$;
-          }, {
-            e: undefined,
-            t: undefined
           });
-          return _el$;
         }
       });
     };
@@ -367,28 +450,15 @@ var tui_default = Plugin.define({
           run: props.close
         }]
       }));
-      return (() => {
-        var _el$18 = _$createElement("box"), _el$19 = _$createElement("text"), _el$21 = _$createElement("scrollbox");
-        _$insertNode(_el$18, _el$19);
-        _$insertNode(_el$18, _el$21);
-        _$setProp(_el$18, "flexDirection", "column");
-        _$setProp(_el$18, "flexGrow", 1);
-        _$setProp(_el$18, "padding", 1);
-        _$insertNode(_el$19, _$createTextNode(`Close \xD7 \xB7 Esc when focused \xB7 Ctrl+P to toggle`));
-        _$setProp(_el$19, "onMouseDown", (event) => {
-          event.stopPropagation();
-          props.close();
-        });
-        _$setProp(_el$21, "flexGrow", 1);
-        _$insert(_el$21, _$createComponent(List, {
-          get sessionID() {
-            return props.sessionID;
-          },
-          full: true
-        }));
-        _$effect((_$p) => _$setProp(_el$19, "fg", ctx.theme.text.base, _$p));
-        return _el$18;
-      })();
+      return _$createComponent(List, {
+        get sessionID() {
+          return props.sessionID;
+        },
+        full: true,
+        get onClose() {
+          return props.close;
+        }
+      });
     };
     const panel = ctx.ui.slot({
       append: "session.panel",
@@ -423,7 +493,6 @@ var tui_default = Plugin.define({
     return () => {
       sidebar();
       panel();
-      notify();
     };
   }
 });

package/index.ts

@@ -13,7 +13,10 @@ import { diffTodos } from "./src/diff.ts"
 import {
   TodoInstructions,
   TodoLifecycleInstructions,
+  TodoNamespaceDescription,
+  TodoReadAliasDescription,
   TodoReadInstructions,
+  TodoWriteAliasDescription,
   TodoWriteInstructions,
 } from "./src/instructions.ts"
 import { Snapshot, TodoError, Todos } from "./src/model.ts"
@@ -107,6 +110,16 @@ export const register = (ctx: TodoPluginContext): Effect.Effect<void, never, Sco
       return session
     })
 
+    const requireRoot = (session: Session.Info): Effect.Effect<Session.Info, Tool.Error> =>
+      session.parentID === undefined
+        ? Effect.succeed(session)
+        : Effect.fail(
+          new Tool.Error({
+            message:
+              "TODO tools are only available in root sessions. Subagent sessions cannot read or update the session's TODO list.",
+          }),
+        )
+
     const directoryFor = (session: Session.Info): Effect.Effect<SessionDirectory, TodoError> =>
       Schema.decodeUnknownEffect(SessionDirectory)({
         directory: session.location.directory,
@@ -135,6 +148,7 @@ export const register = (ctx: TodoPluginContext): Effect.Effect<void, never, Sco
     )(function*(input, context): Effect.fn.Return<Tool.Result<typeof Snapshot>, Tool.Error> {
       const session: Session.Info = yield* getSession(context.sessionID).pipe(
         Effect.mapError(toolError),
+        Effect.flatMap(requireRoot),
       )
       const agent: Agent.Info = (yield* ctx.agent
         .get({ agentID: context.agent })
@@ -186,19 +200,26 @@ export const register = (ctx: TodoPluginContext): Effect.Effect<void, never, Sco
     const executeRead: Tool.Info<typeof ReadInput, typeof Snapshot>["execute"] = (
       _input,
       context,
-    ): Effect.Effect<Tool.Result<typeof Snapshot>, Tool.Error> => {
-      return read(context.sessionID).pipe(
-        Effect.map(
-          (snapshot): Tool.Result<typeof Snapshot> => ({
-            output: snapshot,
-            content: JSON.stringify(snapshot),
-          }),
-        ),
-        Effect.mapError(toolError),
-      )
-    }
+    ): Effect.Effect<Tool.Result<typeof Snapshot>, Tool.Error> =>
+      Effect.gen(function*(): Effect.fn.Return<Tool.Result<typeof Snapshot>, Tool.Error> {
+        const session: Session.Info = yield* getSession(context.sessionID).pipe(
+          Effect.mapError(toolError),
+          Effect.flatMap(requireRoot),
+        )
+        return yield* directoryFor(session).pipe(
+          Effect.flatMap(store.read),
+          Effect.map(
+            (snapshot): Tool.Result<typeof Snapshot> => ({
+              output: snapshot,
+              content: JSON.stringify(snapshot),
+            }),
+          ),
+          Effect.mapError(toolError),
+        )
+      })
 
     yield* ctx.tool.transform((editor): void => {
+      editor.namespace({ name: "todo", description: TodoNamespaceDescription })
       editor.add({
         name: "todowrite",
         description: `${TodoWriteInstructions}\n\n${TodoLifecycleInstructions}`,
@@ -215,6 +236,22 @@ export const register = (ctx: TodoPluginContext): Effect.Effect<void, never, Sco
         options: { codemode: false, permission: "todowrite" },
         execute: executeRead,
       })
+      editor.add({
+        name: "write",
+        description: TodoWriteAliasDescription,
+        input: WriteInput,
+        output: Snapshot,
+        options: { namespace: "todo", codemode: true, pinned: true, permission: "todowrite" },
+        execute: executeWrite,
+      })
+      editor.add({
+        name: "read",
+        description: TodoReadAliasDescription,
+        input: ReadInput,
+        output: Snapshot,
+        options: { namespace: "todo", codemode: true, pinned: true, permission: "todowrite" },
+        execute: executeRead,
+      })
     })
   }).pipe(Effect.orDie)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-session-todo",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Session-local todo.txt tools and TUI for OpenCode V2",
   "homepage": "https://github.com/alexandru/opencode-todo#readme",
   "bugs": {
@@ -23,10 +23,8 @@
     "dist",
     "rpc.ts",
     "src",
-    "USAGE.md",
     "LICENSE",
-    "README.md",
-    "docs/development.md"
+    "README.md"
   ],
   "scripts": {
     "build": "bun run build.ts",

package/src/instructions.ts

@@ -4,7 +4,7 @@ Replace this session’s TODO list.
 
 - You MUST pass the last known saved list as \`previous\`; use \`[]\` when known empty.
 - You SHOULD reuse the returned saved list for subsequent writes.
-- On conflict, you MUST call \`todoread\` and retry.`
+- On conflict, you MUST refresh the saved list and retry.`
 
 export const TodoReadInstructions: string = `### \`todoread\`
 
@@ -14,6 +14,12 @@ Read this session’s saved TODO list and storage path.
 
 export const TodoLifecycleInstructions: string = `### TODO lifecycle
 
+- You MUST create a TODO list when you have more than one work item to track.
+- You MUST NOT create a TODO list for a straightforward question or a single work item.
+- You MUST NOT split a single work item into artificial steps just to justify a TODO list.
+
+The following rules apply only when a TODO list is needed or already tracks unfinished work.
+
 - You MUST keep this session's TODO list synchronized with the requested work and its actual progress.
 - You MUST preserve existing tasks, order, statuses, and priorities unless actual progress or the user's instructions require a change.
 - You MUST mark a task in_progress before starting it. You MUST keep at most one task in_progress.
@@ -23,5 +29,30 @@ export const TodoLifecycleInstructions: string = `### TODO lifecycle
 - Before your final response, you MUST reconcile the list with what was actually done and accurately retain unfinished work.
 - You SHOULD keep task descriptions concise and actionable.`
 
+export const TodoCodeModeInstructions: string = `### Code Mode
+
+- You SHOULD prefer Code Mode for TODO updates.
+- When the current list is known, call \`tools.todo.write\` directly with that \`previous\` list; do not read first.
+- Read with \`tools.todo.read()\` only when the saved list is unknown or a write reports a conflict.
+- When you need both, perform them sequentially in one execute call: await the read, pass the returned \`todos\` as \`previous\`, await the write, and return only the final snapshot.
+- You MUST NOT use \`Promise.all\` for dependent TODO operations.
+- You MUST NOT batch lifecycle transitions in one call.
+
+\`\`\`ts
+const { todos } = await tools.todo.read()
+return await tools.todo.write({
+  previous: todos,
+  todos: [...todos, { content: "Run the tests", status: "pending", priority: "high" }],
+})
+\`\`\``
+
+export const TodoWriteAliasDescription: string = "Replace this session’s TODO list."
+
+export const TodoReadAliasDescription: string =
+  "Read this session’s saved TODO list and storage path."
+
+export const TodoNamespaceDescription: string =
+  "Session TODO list tools. Prefer one execute call per update: write with the last known list; read only when the saved list is unknown or a write reports a conflict."
+
 export const TodoInstructions: string =
-  `${TodoWriteInstructions}\n\n${TodoReadInstructions}\n\n${TodoLifecycleInstructions}`
+  `${TodoWriteInstructions}\n\n${TodoReadInstructions}\n\n${TodoLifecycleInstructions}\n\n${TodoCodeModeInstructions}`

package/src/store.ts

@@ -65,21 +65,31 @@ const requireDirectory = async (directory: string): Promise<void> => {
   }
 }
 
-const load = Effect.fnUntraced(function*(path: string): Effect.fn.Return<Document, TodoError> {
-  const text: string = yield* io(`Cannot read ${path}`, async (): Promise<string> => {
-    try {
-      const info: Stats = await lstat(path)
-      if (!info.isFile()) {
-        throw new Error("todo.txt must be a regular file")
-      }
-      return await readFile(path, "utf8")
-    } catch (error) {
-      if (missing(error)) return ""
-      throw error
-    }
-  })
-  return yield* parse(text)
-})
+interface LoadedDocument extends Document {
+  readonly exists: boolean
+}
+
+const load = Effect.fnUntraced(
+  function*(path: string): Effect.fn.Return<LoadedDocument, TodoError> {
+    const file: { readonly text: string; readonly exists: boolean } = yield* io(
+      `Cannot read ${path}`,
+      async (): Promise<{ readonly text: string; readonly exists: boolean }> => {
+        try {
+          const info: Stats = await lstat(path)
+          if (!info.isFile()) {
+            throw new Error("todo.txt must be a regular file")
+          }
+          return { text: await readFile(path, "utf8"), exists: true }
+        } catch (error) {
+          if (missing(error)) return { text: "", exists: false }
+          throw error
+        }
+      },
+    )
+    const document: Document = yield* parse(file.text)
+    return { ...document, exists: file.exists }
+  },
+)
 
 const checkDirectory = Effect.fnUntraced(function*(
   session: SessionDirectory,
@@ -132,13 +142,16 @@ export const makeTodoStore: Effect.Effect<TodoStore> = Effect.gen(
           Effect.gen(function*(): Effect.fn.Return<WriteResult, TodoError> {
             const path: string = pathFor(session)
             yield* ensureDirectory(session)
-            const previous: Document = yield* load(path)
+            const previous: LoadedDocument = yield* load(path)
             if (expected !== undefined && !sameTodos(expected, previous.todos)) {
               return yield* new TodoError({
                 message:
-                  "The stored todo list does not match the `previous` list you sent. Use todoread, then retry todowrite with the refreshed `previous` list.",
+                  "The stored todo list does not match the `previous` list you sent. Use todoread or tools.todo.read(), then retry todowrite with the refreshed `previous` list.",
               })
             }
+            if (previous.exists && sameTodos(todos, previous.todos)) {
+              return { path, todos, previous: previous.todos }
+            }
             const temporary: string = `${path}.${randomUUID()}.tmp`
             const today: string = DateTime.formatIsoDateUtc(yield* DateTime.now)
             yield* io(`Cannot write ${path}`, async (): Promise<void> => {
@@ -149,8 +162,9 @@ export const makeTodoStore: Effect.Effect<TodoStore> = Effect.gen(
                   flag: "wx",
                 })
                 await rename(temporary, path)
-              } finally {
+              } catch (error) {
                 await rm(temporary, { force: true })
+                throw error
               }
             })
             return { path, todos, previous: previous.todos }

package/tui.tsx

@@ -17,17 +17,16 @@ import {
 import { TodoRpc } from "./rpc.ts"
 import { type Snapshot, type Todo } from "./src/model.ts"
 import { projectTodos, SidebarOptions, type TodoProjection } from "./src/sidebar.ts"
-import { formatTodo } from "./src/summary.ts"
+import { formatTodo, todoSymbols } from "./src/summary.ts"
 
 type View =
   | { readonly status: "loading" }
   | { readonly status: "ready"; readonly snapshot: Snapshot }
   | { readonly status: "error"; readonly message: string }
 
-interface Props {
-  readonly sessionID: string
-  readonly full?: boolean
-}
+type Props =
+  | { readonly sessionID: string; readonly full: true; readonly onClose: () => void }
+  | { readonly sessionID: string; readonly full?: false; readonly onClose?: never }
 
 const colorFor = (
   status: Todo["status"],
@@ -45,6 +44,12 @@ const colorFor = (
   }
 }
 
+const priorityBadge: Readonly<Record<Todo["priority"], string>> = {
+  high: "(A)",
+  medium: "(B)",
+  low: "(C)",
+}
+
 const Message = Schema.Struct({ message: Schema.String })
 const messageFor = (error: unknown): string =>
   Schema.is(Message)(error) ? error.message : String(error)
@@ -65,15 +70,6 @@ export default Plugin.define({
     const [sidebarView, updateSidebarView] = ctx.storage.store("sidebar", {
       initial: { open: true },
     })
-    const notify: () => void = api.events.on("updated", (event): void => {
-      if (event.data.summary === "") return
-      ctx.ui.toast.show({
-        title: "TODO updated",
-        message: event.data.summary,
-        variant: "info",
-        sessionID: event.data.sessionID,
-      })
-    })
     const List = (props: Props): JSX.Element => {
       const [view, setView] = createSignal<View>({ status: "loading" })
       createEffect((): void => {
@@ -160,64 +156,125 @@ export default Plugin.define({
       }
       const visible: Accessor<boolean> = (): boolean =>
         Boolean(props.full || snapshot()?.todos.length || error())
-      return (
-        <Show when={visible()}>
-          <box flexDirection="column" gap={0} paddingTop={1}>
-            <box
-              flexDirection="row"
-              gap={1}
-              onMouseDown={(event: MouseEvent): void => {
-                if (props.full) return
-                event.stopPropagation()
-                void updateSidebarView((draft): void => {
-                  draft.open = !draft.open
-                }).catch((error: unknown): void => {
-                  ctx.ui.toast.show({
-                    title: "Todo sidebar",
-                    message: `Cannot save expanded state: ${messageFor(error)}`,
-                    variant: "error",
-                  })
-                })
-              }}
-            >
-              <Show when={!props.full}>
-                <text fg={ctx.theme.text.base}>{sidebarView.open ? "▼" : "▶"}</text>
-              </Show>
-              <text fg={ctx.theme.text.base}>
-                <b>TODO</b>
-                <span style={{ fg: ctx.theme.text.muted }}>{" "}({active()} remaining)</span>
+      const Header = (): JSX.Element => (
+        <box
+          flexDirection="row"
+          gap={1}
+          flexShrink={0}
+          paddingBottom={props.full ? 1 : 0}
+          onMouseDown={(event: MouseEvent): void => {
+            if (props.full) return
+            event.stopPropagation()
+            void updateSidebarView((draft): void => {
+              draft.open = !draft.open
+            }).catch((error: unknown): void => {
+              ctx.ui.toast.show({
+                title: "Todo sidebar",
+                message: `Cannot save expanded state: ${messageFor(error)}`,
+                variant: "error",
+              })
+            })
+          }}
+        >
+          <Show when={!props.full}>
+            <text fg={ctx.theme.text.base}>{sidebarView.open ? "▼" : "▶"}</text>
+          </Show>
+          <box flexGrow={1} flexShrink={1} minWidth={0}>
+            <text fg={ctx.theme.text.base}>
+              <b>TODO</b>
+              <span style={{ fg: ctx.theme.text.muted }}>{" "}({active()} remaining)</span>
+            </text>
+          </box>
+          <Show when={props.full ? props.onClose : undefined}>
+            {(onClose: Accessor<() => void>): JSX.Element => (
+              <text
+                fg={ctx.theme.text.muted}
+                flexShrink={0}
+                selectable={false}
+                onMouseDown={(event: MouseEvent): void => {
+                  event.stopPropagation()
+                  onClose()()
+                }}
+              >
+                ×
               </text>
-            </box>
-            <Show when={props.full || sidebarView.open}>
-              <Show when={props.full}>
-                <text fg={ctx.theme.text.muted}>{snapshot()?.path ?? "Loading todo.txt…"}</text>
-              </Show>
-              <Show when={error()}>
-                <text fg={ctx.theme.text.feedback.error.base}>Cannot read todos: {error()}</text>
-              </Show>
-              <Show when={props.full && view().status === "ready" && todos().length === 0}>
-                <text fg={ctx.theme.text.muted}>No todos for this session.</text>
-              </Show>
+            )}
+          </Show>
+        </box>
+      )
+      const Body = (): JSX.Element => (
+        <>
+          <Show when={error()}>
+            <text fg={ctx.theme.text.feedback.error.base}>Cannot read todos: {error()}</text>
+          </Show>
+          <Show when={props.full && view().status === "ready" && todos().length === 0}>
+            <text fg={ctx.theme.text.muted}>No todos for this session.</text>
+          </Show>
+          <Show
+            when={props.full}
+            fallback={
               <For each={todos()}>
                 {(todo): JSX.Element => (
-                  <text fg={colorFor(todo.status, ctx.theme)}>
-                    {formatTodo(todo)}
-                  </text>
+                  <text fg={colorFor(todo.status, ctx.theme)}>{formatTodo(todo)}</text>
                 )}
               </For>
-              <Show when={more()}>
-                <text
-                  fg={ctx.theme.text.feedback.info.base}
-                  onMouseDown={(event: MouseEvent): void => {
-                    event.stopPropagation()
-                    ctx.ui.panel.open("session-todo.list")
-                  }}
-                >
-                  Show all {more()} todos →
-                </text>
-              </Show>
-            </Show>
-          </box>
+            }
+          >
+            <For each={todos()}>
+              {(todo): JSX.Element => (
+                <box flexDirection="row" gap={1}>
+                  <text
+                    fg={colorFor(todo.status, ctx.theme)}
+                    width={3}
+                    flexShrink={0}
+                  >
+                    {todoSymbols[todo.status]}
+                  </text>
+                  <box flexGrow={1} flexShrink={1} minWidth={0}>
+                    <text fg={colorFor(todo.status, ctx.theme)} wrapMode="word">
+                      {todo.content}
+                    </text>
+                  </box>
+                  <text fg={ctx.theme.text.muted} width={3} flexShrink={0}>
+                    {priorityBadge[todo.priority]}
+                  </text>
+                </box>
+              )}
+            </For>
+          </Show>
+          <Show when={more()}>
+            <text
+              fg={ctx.theme.text.feedback.info.base}
+              onMouseDown={(event: MouseEvent): void => {
+                event.stopPropagation()
+                ctx.ui.panel.open("session-todo.list")
+              }}
+            >
+              Show all {more()} todos →
+            </text>
+          </Show>
+        </>
+      )
+      return (
+        <Show when={visible()}>
+          <Show
+            when={props.full}
+            fallback={
+              <box flexDirection="column" gap={0} paddingTop={1}>
+                <Header />
+                <Show when={sidebarView.open}>
+                  <Body />
+                </Show>
+              </box>
+            }
+          >
+            <box flexDirection="column" flexGrow={1} minHeight={0} padding={1}>
+              <Header />
+              <scrollbox flexGrow={1} flexBasis={0} minHeight={0}>
+                <Body />
+              </scrollbox>
+            </box>
+          </Show>
         </Show>
       )
     }
@@ -240,22 +297,7 @@ export default Plugin.define({
           ],
         }),
       )
-      return (
-        <box flexDirection="column" flexGrow={1} padding={1}>
-          <text
-            fg={ctx.theme.text.base}
-            onMouseDown={(event: MouseEvent): void => {
-              event.stopPropagation()
-              props.close()
-            }}
-          >
-            Close × · Esc when focused · Ctrl+P to toggle
-          </text>
-          <scrollbox flexGrow={1}>
-            <List sessionID={props.sessionID} full />
-          </scrollbox>
-        </box>
-      )
+      return <List sessionID={props.sessionID} full onClose={props.close} />
     }
     const panel: () => void = ctx.ui.slot({
       append: "session.panel",
@@ -287,7 +329,6 @@ export default Plugin.define({
     return (): void => {
       sidebar()
       panel()
-      notify()
     }
   },
 })

package/USAGE.md

@@ -1,83 +0,0 @@
-# Session TODOs
-
-## Setup
-
-Configure the plugin in `opencode.jsonc`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugins": [{ "package": "opencode-session-todo", "options": { "sidebarLimit": 5 } }]
-}
-```
-
-Then reload OpenCode:
-
-```sh
-opencode reload
-```
-
-Reopen the TUI after configuration changes. `sidebarLimit` is a positive integer, default **5**.
-
-## Tools
-
-Only root sessions expose these tools and receive the TODO lifecycle instructions. Subagents see neither tool.
-
-- `todoread({})` reads the current session's tasks and file path. Missing files return an empty list.
-- `todowrite({ previous, todos })` replaces the ordered list only when the stored list still equals `previous`; take `previous` from the latest `todoread` or `todowrite` result. A mismatch fails with an instruction to `todoread` and retry. The result reports a before/after diff. An empty `todos` array clears the list.
-
-```json
-{
-  "previous": [],
-  "todos": [
-    { "content": "Run the tests", "status": "in_progress", "priority": "high" }
-  ]
-}
-```
-
-Statuses: `pending`, `in_progress`, `completed`, `cancelled`. Priorities: `high`, `medium`, `low`.
-At most one task may be `in_progress`. Content must be one nonempty trimmed line,
-cannot begin with a priority/date, and cannot contain `status:` or `pri:` tokens.
-
-## TUI
-
-- Click **TODO** or its `▼` / `▶` arrow to expand or collapse the sidebar list.
-- Above `sidebarLimit` total tasks, the sidebar shows only unfinished tasks, capped at the limit,
-  with the active task first.
-- **Show all …**, `/todos`, or **Ctrl+P → Toggle session todos** opens the full scrollable panel.
-- Close with **Close ×**, **Esc** while focused, or the same command-palette action.
-- Update toasts show only added or changed tasks, one line each, with the new status and priority.
-- Manual file edits appear within two seconds. Collapsing does not change the tasks.
-
-## Storage
-
-```text
-<project/worktree>/.agents/sessions/<session-id>/todo.txt
-```
-
-```text
-(A) Run the tests status:in_progress
-(B) Review the changes
-x Read the docs pri:C
-x Superseded approach pri:B status:cancelled
-```
-
-`A` / `B` / `C` map to high / medium / low; other priority letters are unsupported.
-Add `.agents/sessions/` to your project's ignore rules to keep these files out of version control.
-
-## Permissions
-
-Both tools use `todowrite`. Writes require agent/session rules resolving to `allow`; `ask` and
-`deny` are rejected. Approval prompts, saved approvals, and experimental policies are unsupported.
-Read-only agents should deny `todowrite`.
-
-## Commands
-
-From the repository root:
-
-```sh
-bun run check
-bun test
-bun run format       # dprint fmt
-bun run format:check # dprint check
-```

package/docs/development.md

@@ -1,28 +0,0 @@
-# Development
-
-Requires Bun >= 1.4.2.
-
-```sh
-bun ci
-make test
-```
-
-`make test` runs typecheck, tests, and formatting checks.
-`make upgrade-dependencies` updates pinned dependencies and the lockfile.
-
-## Package entry points
-
-The package ships TypeScript sources for OpenCode's Bun runtime and precompiled Solid ESM for the TUI. Run `bun run build` before loading the local package; packing builds the TUI automatically.
-
-- `opencode-session-todo`: tools and RPC handlers.
-- `opencode-session-todo/tui`: sidebar and full panel.
-- `opencode-session-todo/rpc`: shared RPC definitions.
-
-## Publishing
-
-```sh
-npm login
-make publish
-```
-
-`make publish` runs the checks and a package dry-run before `npm publish --access public`.