@oisin-ee/pi-todo 0.2.0 → 0.4.0

package/README.md

@@ -27,9 +27,50 @@ and the list stays as it was.
 
 ## State
 
-Each change is saved as a `todo-state` entry on the session branch. There is no other state. So a resumed session,
-a `/tree` move, and calls made from inside codemode all see the list of the current branch. A widget shows the list
-while it has tasks, and `/todos` prints it.
+Each task change is saved as a `todo-state` entry on the session branch. A resumed session, a `/tree` move,
+and calls made from inside codemode all see the list of the current branch.
+
+## Widget
+
+The widget shows only in-progress tasks by default. Active tasks use the theme accent and bold text.
+Long task names wrap to the terminal width. An empty list has no widget.
+
+Press **Alt+T** to expand Upcoming, Done, and Dropped sections beneath the active task. Press **Alt+T** again to collapse them.
+`/todos` also toggles these sections. `/todos list` prints the full list.
+
+Expansion stays open through task updates. Session changes and `/tree` navigation collapse it. Expansion does not change saved tasks.
+When no task is active, a short status and the shortcut hint remain visible.
+Outside the terminal UI, `/todos` prints the list instead.
+
+## Shared work display
+
+When a compatible pi-wrangle extension is active, its `WORK` strip replaces the standalone todo widget.
+Tasks remain on the current Pi session branch. Wrangle receives read-only snapshots through `pi.events`.
+`/todos` and Alt+T request the shared Todos view. `/todos list` still prints the full list.
+When shared presentation ends, the standalone widget returns without changing task state.
+
+The [version 1 display contract](https://github.com/oisin-ee/wrangle/blob/main/docs/pi-work.md)
+defines the snapshot request, acknowledgement, release, and read-only view events.
+
+## Plannotator plans
+
+With Plannotator external execution, pi-todo continues approved plans in the same session.
+Add this setting to `~/.pi/agent/plannotator.json`:
+
+```json
+{
+  "executionMode": "external"
+}
+```
+
+After approval, the agent reads the current todo list and adds the remaining approved work before implementation.
+It preserves unrelated tasks and completed progress. Free-form plans do not need a special checklist format.
+The todo tool owns progress, persistence, reminders, and the shared work display.
+Plannotator returns to idle and does not maintain a second checklist or require `[DONE:n]` markers.
+
+This integration uses the supported `plannotator:plan-approved` event, verified with Plannotator `0.28.19`.
+It does not import Plannotator internals or change its code.
+Malformed events, a different working directory, or another owner of the `todo` tool stop the handoff with an error.
 
 ## Reminder
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-todo",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A todo tool for pi with a Rust core: one active task, state on the session branch.",
   "keywords": [
     "pi-extension",
@@ -21,11 +21,13 @@
   "devDependencies": {
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
     "typebox": "1.3.27"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "pi": {

package/src/generated/todo_core.d.ts

@@ -24,6 +24,14 @@ export interface Request {
     task: string | undefined;
 }
 
+/**
+ * One row before terminal wrapping and theme application.
+ */
+export interface WidgetRow {
+    kind: WidgetKind;
+    text: string;
+}
+
 /**
  * One task, addressed by its exact content.
  */
@@ -37,6 +45,11 @@ export interface Task {
  */
 export type ReminderFact = { kind: "user" } | { kind: "snapshot"; list: TodoList } | { kind: "reminder" };
 
+/**
+ * Semantic styling for a terminal row.
+ */
+export type WidgetKind = "heading" | "active" | "upcoming" | "done" | "dropped" | "summary";
+
 /**
  * Supported model-facing operations.
  */
@@ -102,13 +115,13 @@ export function parse(snapshot: unknown): TodoList;
 export function view(list: TodoList): string;
 
 /**
- * The widget lines for `list`, or `undefined` for an empty list.
+ * Human-facing rows for `list`, or `undefined` for an empty list.
  *
  * # Errors
  *
  * Throws when `list` is not a valid todo list.
  */
-export function widget(list: TodoList): string[] | undefined;
+export function widget(list: TodoList, expanded: boolean): WidgetRow[] | undefined;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
@@ -119,7 +132,7 @@ export interface InitOutput {
     readonly init: (a: number, b: number, c: number) => void;
     readonly parse: (a: number, b: number) => void;
     readonly view: (a: number, b: number) => void;
-    readonly widget: (a: number, b: number) => void;
+    readonly widget: (a: number, b: number, c: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/src/generated/todo_core.js

@@ -149,18 +149,19 @@ export function view(list) {
 }
 
 /**
- * The widget lines for `list`, or `undefined` for an empty list.
+ * Human-facing rows for `list`, or `undefined` for an empty list.
  *
  * # Errors
  *
  * Throws when `list` is not a valid todo list.
  * @param {TodoList} list
- * @returns {string[] | undefined}
+ * @param {boolean} expanded
+ * @returns {WidgetRow[] | undefined}
  */
-export function widget(list) {
+export function widget(list, expanded) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.widget(retptr, addBorrowedObject(list));
+        wasm.widget(retptr, addBorrowedObject(list), expanded);
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);

package/src/generated/todo_core_bg.wasm.d.ts

@@ -6,7 +6,7 @@ export const completion_reminder: (a: number, b: number) => void;
 export const init: (a: number, b: number, c: number) => void;
 export const parse: (a: number, b: number) => void;
 export const view: (a: number, b: number) => void;
-export const widget: (a: number, b: number) => void;
+export const widget: (a: number, b: number, c: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/src/index.ts

@@ -1,12 +1,26 @@
-import { ownsTodo, replay, settle, show, start } from "./lifecycle.ts";
+import { ownsTodo, settle } from "./lifecycle.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { PlannotatorHandoff } from "./plannotator.ts";
 import { StringEnum } from "@earendil-works/pi-ai";
+import { TodoPresentation } from "./presentation.ts";
+import { TodoWork } from "./work.ts";
 import { Type } from "typebox";
+import type { WorkHost } from "./work.ts";
 import { runTodo } from "./tool.ts";
 
-type TodoAPI = Readonly<
-  Pick<ExtensionAPI, "appendEntry" | "getAllTools" | "on" | "registerCommand" | "registerTool">
->;
+type TodoAPI = WorkHost &
+  Readonly<
+    Pick<
+      ExtensionAPI,
+      | "appendEntry"
+      | "getAllTools"
+      | "on"
+      | "registerCommand"
+      | "registerShortcut"
+      | "registerTool"
+      | "sendMessage"
+    >
+  >;
 
 const items = Type.Immutable(
     Type.Array(Type.String(), { description: "For init or append: tasks, in order." }),
@@ -27,6 +41,10 @@ const items = Type.Immutable(
  * @param {TodoAPI} pi The extension API methods used here.
  */
 export default function piTodo(pi: TodoAPI): void {
+  const handoff = new PlannotatorHandoff(pi),
+    presentation = new TodoPresentation(),
+    work = new TodoWork(pi, presentation);
+  work.register(pi);
   pi.registerTool({
     description:
       "Keep the session todo list. Tasks are addressed by their exact content. One task is active; the next open task starts when it closes.",
@@ -37,7 +55,8 @@ export default function piTodo(pi: TodoAPI): void {
         },
         branch: () => ctx.sessionManager.getBranch(),
       });
-      replay(ctx);
+      work.publish(ctx);
+      presentation.refresh(ctx);
       return result;
     },
     executionMode: "sequential",
@@ -46,18 +65,19 @@ export default function piTodo(pi: TodoAPI): void {
     parameters,
   });
   pi.on("session_start", (_event, ctx) => {
-    start(pi, ctx);
+    presentation.start(pi, ctx);
+    work.start(ctx);
+    handoff.start(ctx);
+  });
+  pi.on("session_shutdown", () => {
+    handoff.stop();
+    work.stop();
   });
   pi.on("session_tree", (_event, ctx) => {
     if (ownsTodo(pi)) {
-      replay(ctx);
+      work.publish(ctx);
+      presentation.reset(ctx);
     }
   });
   pi.on("agent_before_settle", (event, ctx) => settle(pi, event, ctx));
-  pi.registerCommand("todos", {
-    description: "Show the todo list on this session branch.",
-    async handler(_args, ctx) {
-      show(ctx);
-    },
-  });
 }

package/src/lifecycle.ts

@@ -1,15 +1,19 @@
 import type {
   BoundaryResult,
+  ExtensionContext,
   ExtensionUIContext,
   SessionBoundaryDraft,
   SessionEntry,
+  Theme,
 } from "@earendil-works/pi-coding-agent";
 import { REMINDER_ENTRY, reminder } from "./reminder.ts";
 import { parse, view, widget } from "./wasm.ts";
+import { TodoWidget } from "./widget.ts";
 import { isOwnSource } from "./source.ts";
 import { latestSnapshot } from "./state.ts";
 
 interface TodoContext {
+  readonly mode: ExtensionContext["mode"];
   readonly sessionManager: { readonly getBranch: () => readonly SessionEntry[] };
   readonly ui: Readonly<Pick<ExtensionUIContext, "notify" | "setWidget">>;
 }
@@ -36,10 +40,21 @@ const ownsTodo = (pi: TodoHost): boolean =>
   /**
    * Renders the selected branch snapshot, and removes the widget when the list is empty.
    * @param {TodoContext} ctx Branch and UI methods.
+   * @param {boolean} expanded Whether to reveal secondary task groups.
    */
-  replay = (ctx: TodoContext): void => {
-    const list = parse(latestSnapshot(ctx.sessionManager.getBranch()));
-    ctx.ui.setWidget("pi-todo", widget(list));
+  replay = (ctx: TodoContext, expanded = false): void => {
+    if (ctx.mode !== "tui") {
+      return;
+    }
+    const list = parse(latestSnapshot(ctx.sessionManager.getBranch())),
+      rows = widget(list, expanded);
+    ctx.ui.setWidget(
+      "pi-todo",
+      rows === undefined
+        ? undefined
+        : (_tui: unknown, theme: Readonly<Pick<Theme, "fg" | "bold">>): TodoWidget =>
+            new TodoWidget(rows, expanded, theme),
+    );
   },
   /**
    * Applies the completion decision at pi's final actionable boundary.

package/src/plannotator.ts

@@ -0,0 +1,107 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { TodoContext } from "./lifecycle.ts";
+import type { WorkHost } from "./work.ts";
+import { ownsTodo } from "./lifecycle.ts";
+
+/** The supported Plannotator external-execution event. */
+interface ApprovedPlan {
+  readonly cwd: string;
+  readonly planFilePath: string;
+  readonly planContent: string;
+  readonly feedback?: string;
+}
+
+type PlanHost = WorkHost & Readonly<Pick<ExtensionAPI, "sendMessage">>;
+type PlanContext = TodoContext & { readonly cwd: string };
+
+/**
+ * Validates the event before it enters the model context.
+ * @param {unknown} value The shared event payload.
+ * @returns {boolean} Whether the required handoff fields are present.
+ */
+const isApprovedPlan = (value: unknown): value is ApprovedPlan =>
+    typeof value === "object" &&
+    value !== null &&
+    "cwd" in value &&
+    typeof value.cwd === "string" &&
+    "planFilePath" in value &&
+    typeof value.planFilePath === "string" &&
+    value.planFilePath.trim() !== "" &&
+    "planContent" in value &&
+    typeof value.planContent === "string" &&
+    value.planContent.trim() !== "" &&
+    (!("feedback" in value) || value.feedback === undefined || typeof value.feedback === "string"),
+  /**
+   * Continues the approved plan through the existing todo tool, not a second parser or store.
+   * @param {ApprovedPlan} plan The approved document and reviewer feedback.
+   * @returns {string} Instructions followed by the exact handoff data.
+   */
+  continuation = (plan: ApprovedPlan): string =>
+    [
+      "The user approved this plan in Plannotator. Continue execution in this session.",
+      "Use the todo tool as the only task tracker. Do not maintain Plannotator [DONE:n] markers.",
+      "First call todo with op=view to inspect the current branch list.",
+      "Before implementation, represent the approved plan's remaining work in that list.",
+      "If the list is empty, call todo with op=init and the remaining approved tasks in order.",
+      "Otherwise, reuse matching tasks and append missing tasks. Preserve unrelated work and completed progress.",
+      "If approved work remains, select its next open task with op=start. Never restart a completed task just because the plan was approved again.",
+      "If no approved work remains, report completion without changing tasks. Otherwise, update tasks with op=done or op=drop as work proceeds.",
+      "Resolve a relative planFilePath against cwd. The approved document and reviewer feedback follow as JSON:",
+      JSON.stringify({
+        cwd: plan.cwd,
+        feedback: plan.feedback,
+        planContent: plan.planContent,
+        planFilePath: plan.planFilePath,
+      }),
+    ].join("\n");
+
+/** Owns the approval subscription, never the todo list or execution progress. */
+class PlannotatorHandoff {
+  readonly #host: PlanHost;
+  #unsubscribe: (() => void) | undefined;
+
+  /**
+   * Keeps the supported event bus and conversation API.
+   * @param {PlanHost} host The Pi methods used by the handoff.
+   */
+  public constructor(host: PlanHost) {
+    this.#host = host;
+  }
+
+  /**
+   * Subscribes with the current session context after startup or replacement.
+   * @param {PlanContext} ctx The current branch and working directory.
+   */
+  public start(ctx: PlanContext): void {
+    this.stop();
+    this.#unsubscribe = this.#host.events.on(
+      "plannotator:plan-approved",
+      (value: unknown): void => {
+        if (!isApprovedPlan(value)) {
+          ctx.ui.notify("pi-todo: Invalid Plannotator approval. No execution started.", "error");
+        } else if (value.cwd !== ctx.cwd) {
+          ctx.ui.notify(
+            "pi-todo: The approved plan belongs to another working directory. No execution started.",
+            "error",
+          );
+        } else if (ownsTodo(this.#host)) {
+          this.#host.sendMessage(
+            { content: continuation(value), customType: "todo-plan-approved", display: true },
+            { deliverAs: "followUp", triggerTurn: true },
+          );
+        } else {
+          ctx.ui.notify("pi-todo: Another extension owns todo. No execution started.", "error");
+        }
+      },
+    );
+  }
+
+  /** Removes the previous session's listener before replacement or shutdown. */
+  public stop(): void {
+    this.#unsubscribe?.();
+    this.#unsubscribe = undefined;
+  }
+}
+
+export { PlannotatorHandoff };
+export type { PlanContext, PlanHost };

package/src/presentation.ts

@@ -0,0 +1,70 @@
+import type { TodoContext, TodoHost } from "./lifecycle.ts";
+import { ownsTodo, replay, start } from "./lifecycle.ts";
+
+/** Owns transient expansion for one extension instance, never task state. */
+class TodoPresentation {
+  #expanded = false;
+  #external = false;
+
+  /**
+   * Replays current branch tasks without changing expansion.
+   * @param {TodoContext} ctx Current branch and UI.
+   */
+  public refresh(ctx: TodoContext): void {
+    if (!this.#external) {
+      replay(ctx, this.#expanded);
+    }
+  }
+
+  /**
+   * Collapses when the session starts or the selected branch changes.
+   * @param {TodoContext} ctx Current branch and UI.
+   */
+  public reset(ctx: TodoContext): void {
+    this.#expanded = false;
+    this.refresh(ctx);
+  }
+
+  /**
+   * Starts collapsed, or leaves another todo owner untouched.
+   * @param {TodoHost} pi Registered tool metadata.
+   * @param {TodoContext} ctx Current branch and UI.
+   */
+  public start(pi: TodoHost, ctx: TodoContext): void {
+    this.#expanded = false;
+    this.#external = false;
+    start(pi, ctx);
+  }
+
+  /**
+   * Yields only this extension's widget to an acknowledged work presenter.
+   * @param {TodoContext} ctx Current terminal UI.
+   */
+  public claim(ctx: TodoContext): void {
+    this.#external = true;
+    ctx.ui.setWidget("pi-todo", undefined);
+  }
+
+  /**
+   * Restores the standalone view without changing task state.
+   * @param {TodoContext} ctx Current terminal UI.
+   */
+  public release(ctx: TodoContext): void {
+    this.#external = false;
+    this.refresh(ctx);
+  }
+
+  /**
+   * Reveals or hides secondary groups without writing session state.
+   * @param {TodoHost} pi Registered tool metadata.
+   * @param {TodoContext} ctx Current branch and UI.
+   */
+  public toggle(pi: TodoHost, ctx: TodoContext): void {
+    if (ownsTodo(pi)) {
+      this.#expanded = !this.#expanded;
+      this.refresh(ctx);
+    }
+  }
+}
+
+export { TodoPresentation };

package/src/wasm.ts

@@ -28,4 +28,6 @@ export type {
   Status,
   Task,
   TodoList,
+  WidgetKind,
+  WidgetRow,
 } from "./generated/todo_core.js";

package/src/widget.ts

@@ -0,0 +1,57 @@
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { WidgetKind, WidgetRow } from "./wasm.ts";
+
+const TODO_SHORTCUT = "alt+t",
+  horizontalPadding = 1,
+  verticalPadding = 0,
+  colors: Readonly<Record<WidgetKind, ThemeColor>> = {
+    active: "accent",
+    done: "success",
+    dropped: "dim",
+    heading: "muted",
+    summary: "muted",
+    upcoming: "text",
+  };
+
+/** The presentation-only component; task state stays on the session branch. */
+class TodoWidget extends Text {
+  readonly #rows: readonly Readonly<WidgetRow>[];
+  readonly #expanded: boolean;
+  readonly #theme: Readonly<Pick<Theme, "fg" | "bold">>;
+
+  /**
+   * Retains unstyled rows so each render uses the current theme.
+   * @param {readonly Readonly<WidgetRow>[]} rows Rust-owned status groups.
+   * @param {boolean} expanded Whether secondary groups are visible.
+   * @param {Readonly<Pick<Theme, "fg" | "bold">>} theme Pi theme helpers.
+   */
+  public constructor(
+    rows: readonly Readonly<WidgetRow>[],
+    expanded: boolean,
+    theme: Readonly<Pick<Theme, "fg" | "bold">>,
+  ) {
+    super("", horizontalPadding, verticalPadding);
+    this.#rows = rows;
+    this.#expanded = expanded;
+    this.#theme = theme;
+  }
+
+  /**
+   * Wraps all task text with Pi's native terminal component.
+   * @param {number} width Available terminal columns.
+   * @returns {string[]} Width-bounded, themed terminal lines.
+   */
+  public override render(width: number): string[] {
+    const lines = this.#rows.map((row) => {
+        const text = this.#theme.fg(colors[row.kind], row.text);
+        return row.kind === "active" ? this.#theme.bold(text) : text;
+      }),
+      action = this.#expanded ? "collapse" : "upcoming / done";
+    lines.push(this.#theme.fg("dim", `Alt+T · ${action}`));
+    this.setText(lines.join("\n"));
+    return super.render(width).map((line) => truncateToWidth(line, width));
+  }
+}
+
+export { TODO_SHORTCUT, TodoWidget };

package/src/work.ts

@@ -0,0 +1,230 @@
+import type { TodoContext, TodoHost } from "./lifecycle.ts";
+import { ownsTodo, show } from "./lifecycle.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { TODO_SHORTCUT } from "./widget.ts";
+import type { TodoPresentation } from "./presentation.ts";
+import { latestSnapshot } from "./state.ts";
+import { parse } from "./wasm.ts";
+
+interface WorkHost extends TodoHost {
+  readonly events: Readonly<ExtensionAPI["events"]>;
+}
+
+type WorkCommands = Readonly<Pick<ExtensionAPI, "registerCommand" | "registerShortcut">>;
+const protocolVersion = 1,
+  initialRevision = 0;
+
+interface WorkContext extends TodoContext {
+  readonly sessionManager: TodoContext["sessionManager"] & {
+    readonly getSessionId: () => string;
+    readonly getLeafId: () => string | null;
+  };
+}
+
+/** The identity of one work presenter requesting this provider's snapshot. */
+interface Presenter {
+  readonly presenter: string;
+  readonly request: string;
+  readonly version: typeof protocolVersion;
+}
+
+/**
+ * Checks a presentation request without trusting an extension's event payload.
+ * @param {unknown} value Event payload.
+ * @returns {boolean} Whether the envelope uses the supported protocol.
+ */
+const isPresenter = (value: unknown): value is Presenter =>
+  typeof value === "object" &&
+  value !== null &&
+  "version" in value &&
+  value.version === protocolVersion &&
+  "presenter" in value &&
+  typeof value.presenter === "string" &&
+  "request" in value &&
+  typeof value.request === "string";
+
+/** Publishes validated branch data; presentation claims never write task state. */
+class TodoWork {
+  readonly #host: WorkHost;
+  readonly #presentation: Readonly<TodoPresentation>;
+  #context: WorkContext | undefined;
+  #publisher = "";
+  #revision = initialRevision;
+  #presenter: Presenter | undefined;
+  #claimed = false;
+  #subscriptions: (() => void)[] = [];
+
+  /**
+   * Keeps the event bus and the existing standalone presentation owner.
+   * @param {WorkHost} host Pi event bus and tool ownership.
+   * @param {Readonly<TodoPresentation>} presentation Standalone display owner.
+   */
+  public constructor(host: WorkHost, presentation: Readonly<TodoPresentation>) {
+    this.#host = host;
+    this.#presentation = presentation;
+  }
+
+  /**
+   * Registers view entrypoints with a shared or standalone presentation target.
+   * @param {WorkCommands} commands Pi command registration.
+   */
+  public register(commands: WorkCommands): void {
+    commands.registerShortcut(TODO_SHORTCUT, {
+      description: "Show todo details.",
+      handler: (ctx): void => {
+        this.#toggle(ctx);
+      },
+    });
+    commands.registerCommand("todos", {
+      description: "Show todo details; /todos list prints the full branch list.",
+      handler: async (args, ctx): Promise<void> => {
+        if (ownsTodo(this.#host)) {
+          if (args.trim() === "list" || ctx.mode !== "tui") {
+            show(ctx);
+          } else {
+            this.#toggle(ctx);
+          }
+        }
+      },
+    });
+  }
+
+  /**
+   * Opens the shared view or toggles the existing standalone view.
+   * @param {TodoContext} ctx Current UI and branch.
+   */
+  #toggle(ctx: TodoContext): void {
+    if (!this.open()) {
+      this.#presentation.toggle(this.#host, ctx);
+    }
+  }
+
+  /**
+   * Subscribes only when this extension owns the terminal todo tool.
+   * @param {WorkContext} ctx Current Pi session.
+   */
+  public start(ctx: WorkContext): void {
+    this.stop();
+    if (ctx.mode !== "tui" || !ownsTodo(this.#host)) {
+      return;
+    }
+    this.#context = ctx;
+    this.#publisher = crypto.randomUUID();
+    this.#revision = initialRevision;
+    this.#subscriptions = [
+      this.#host.events.on("oisin.work.request", (value: unknown): void => {
+        if (isPresenter(value)) {
+          this.#presenter = value;
+          if (this.#context !== undefined) {
+            this.publish(this.#context);
+          }
+        }
+      }),
+      this.#host.events.on("oisin.work.claim", (value: unknown): void => {
+        this.#claim(value);
+      }),
+      this.#host.events.on("oisin.work.release", (value: unknown): void => {
+        if (this.#matches(value)) {
+          this.#release();
+        }
+      }),
+    ];
+    this.#host.events.emit("oisin.todo.ready", { publisher: this.#publisher, version: 1 });
+  }
+
+  /**
+   * Publishes the actual branch snapshot after tool or branch changes.
+   * @param {WorkContext} ctx Current Pi session, never a stored file's last entry.
+   */
+  public publish(ctx: WorkContext): void {
+    if (this.#context === undefined || this.#presenter === undefined) {
+      return;
+    }
+    this.#context = ctx;
+    this.#revision += 1;
+    const list = parse(latestSnapshot(ctx.sessionManager.getBranch()));
+    this.#host.events.emit("oisin.todo.snapshot", {
+      branch: ctx.sessionManager.getLeafId(),
+      presenter: this.#presenter.presenter,
+      publisher: this.#publisher,
+      request: this.#presenter.request,
+      revision: this.#revision,
+      session: ctx.sessionManager.getSessionId(),
+      tasks: list.tasks,
+      version: 1,
+    });
+  }
+
+  /**
+   * Requests the read-only Todos view without changing expansion or task state.
+   * @returns {boolean} Whether a shared presenter owns the view.
+   */
+  public open(): boolean {
+    if (!this.#claimed || this.#presenter === undefined) {
+      return false;
+    }
+    this.#host.events.emit("oisin.work.open", {
+      presenter: this.#presenter.presenter,
+      request: this.#presenter.request,
+      version: 1,
+      view: "todos",
+    });
+    return true;
+  }
+
+  /** Releases subscriptions and tells the presenter to discard this provider. */
+  public stop(): void {
+    for (const unsubscribe of this.#subscriptions) {
+      unsubscribe();
+    }
+    this.#subscriptions = [];
+    if (this.#context !== undefined) {
+      this.#host.events.emit("oisin.todo.stop", { publisher: this.#publisher, version: 1 });
+    }
+    this.#release();
+    this.#context = undefined;
+  }
+
+  /**
+   * Accepts only an acknowledgement of the latest published snapshot.
+   * @param {unknown} value Claim envelope.
+   */
+  #claim(value: unknown): void {
+    if (
+      this.#matches(value) &&
+      "publisher" in value &&
+      value.publisher === this.#publisher &&
+      "revision" in value &&
+      value.revision === this.#revision &&
+      this.#context !== undefined
+    ) {
+      this.#claimed = true;
+      this.#presentation.claim(this.#context);
+    }
+  }
+
+  /**
+   * Matches a live presenter, excluding delayed messages from replaced sessions.
+   * @param {unknown} value Event envelope.
+   * @returns {boolean} Whether the envelope belongs to the current presenter.
+   */
+  #matches(value: unknown): value is Presenter {
+    return (
+      isPresenter(value) &&
+      value.presenter === this.#presenter?.presenter &&
+      value.request === this.#presenter.request
+    );
+  }
+
+  /** Restores the standalone display when shared presentation ends. */
+  #release(): void {
+    this.#claimed = false;
+    this.#presenter = undefined;
+    if (this.#context !== undefined) {
+      this.#presentation.release(this.#context);
+    }
+  }
+}
+
+export { TodoWork };
+export type { WorkContext, WorkHost };