@hacky.software/opencode-todo-supervisor 0.0.0-stage → 0.3.2

package/LICENSE

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

package/README.md

@@ -1,3 +1,367 @@
-# Temporary Holding Version
+# todo-supervisor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [OpenCode](https://opencode.ai) **V2** plugin that gives every session a real
+todo list — and then keeps the agent working on it. A live progress strip in the
+composer (`📋 ███░░░░░ 8/17 open`) tracks the list.
+
+- `todo_write` / `todo_read` tools (V2 ships none), stored per session;
+- a **supervisor** that re-prompts an idle session while its list still has open
+  items — and stays quiet while the agent is actually working (thinking,
+  preparing a tool, a running tool or `task` subagent, background shells, child
+  sessions), nudging only once that work goes silent;
+- **Markdown mode**: subscribe any number of markdown files whose GFM checklists
+  (`- [ ]`) count as todos — and check them off from the panel;
+- a TUI strip + popover panel, slash command, palette entries, and toasts.
+
+Nudges are delivered as synthetic session input, so the model sees them as normal
+instructions. Every nudge is self-contained: counts, the open items (with
+priorities), a short explainer of why it fired, and how to finish.
+
+Tested against OpenCode `2.0.24`.
+
+## Install
+
+```sh
+opencode plugin add @hacky.software/opencode-todo-supervisor@0.3.2
+```
+
+This also loads the bundled TUI entry. To pass options, use the object form:
+
+```jsonc
+// ~/.config/opencode/opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "@hacky.software/opencode-todo-supervisor",
+      "options": {
+        "stallMinutes": 5,
+        "settleMs": 5000,
+        "minNudgeIntervalMs": 45000,
+        "maxNoProgressNudges": 5,
+        "injectTodoContext": true,
+        "markdownFiles": ["PLAN.md", "TODO.md"],
+        "scope": "project"
+      }
+    }
+  ]
+}
+```
+
+### Development
+
+To run from a checkout instead, point the config at the directory and run
+`bun install` once inside it (the loader does not install dependencies for
+local-path entries). Config content and plugin source edits are hot-reloaded.
+
+```jsonc
+{
+  "plugins": [{ "package": "/absolute/path/to/todo" }]
+}
+```
+
+- Logs: the plugin appends to `~/.local/share/opencode/log/todo-supervisor.log`
+  (prefixes `[todo-supervisor]` / `[todo-supervisor/tui]`). `console.log` inside
+  plugins is swallowed; use the log file.
+
+## What it does
+
+OpenCode has no built-in todo list, so the model often plans in prose and then
+stops early, leaving half a task done. This plugin gives the model a durable list
+and makes finishing it the path of least resistance:
+
+1. the agent calls **`todo_write`** to lay out the work;
+2. it works the list, calling `todo_write` as items move;
+3. if it goes idle with items still open, the **supervisor** nudges it to
+   continue — and if work *looks* running but has gone silent, it nudges about
+   that instead;
+4. it is finished when no open items remain across all sources.
+
+## Tools
+
+Four tools, all registered with `codemode: true` so Code Mode agents can call
+them too. Together they are the whole interface the model uses.
+
+### `todo_write`
+
+Replaces the session's list.
+
+```json
+{
+  "todos": [
+    {
+      "content": "string",
+      "status": "pending | in_progress | completed | canceled",
+      "priority": "high | medium | low"
+    }
+  ]
+}
+```
+
+`content` and `status` are required; `priority` is optional.
+
+- The list **replaces** the previous one — always send the complete list.
+- At most one item may be `in_progress`; extra ones are demoted to `pending` and
+  the result says so.
+- Content is trimmed, empty entries dropped, duplicates removed.
+- Returns the summary plus the canonical list, and resets the supervisor's
+  no-progress counter and any pause.
+
+### `todo_read`
+
+Input is `{}`. Returns the current list merged with subscribed markdown files
+(`path:line` references), or `No todos.` when empty. The list is also injected
+into context on every request, so this is only to double-check exact state.
+
+### `todo_subscribe`
+
+```json
+{ "files": [{ "path": "string" }] }
+```
+
+Treats each file's GFM checklist (`- [ ]`) as todos for this session. Paths are
+relative to the project directory (or absolute) and must end in `.md`/`.markdown`.
+Returns the resulting subscription set.
+
+### `todo_unsubscribe`
+
+Same input as `todo_subscribe`. Stops supervising a file, and also shadows a
+`markdownFiles` config default.
+
+## Markdown mode
+
+Subscribe files with `todo_subscribe`, the panel (`a` / `d`), or config. The
+effective set is `config.markdownFiles ∪ stored files − removed` per session.
+
+- Conventions: `- [ ]` open, `- [x]`/`- [X]` completed, `- [~]` canceled. `-`,
+  `*`, `+`, numbered and indented items all count; fenced code blocks are ignored.
+- Completion by the agent happens by **editing the file** (`- [x]`); nudge text
+  says so explicitly. The **panel can toggle a file item too** (`x`/`space` on a
+  markdown row): the plugin rewrites only that line's marker (indentation,
+  bullet, trailing text and CRLF endings preserved) and refuses paths that are
+  not subscribed.
+- Item references are `path:line`, in both `todo_read` and nudges (grouped:
+  session list first, then one section per file).
+- Missing files are valid subscriptions (0 tasks) and are picked up once created.
+
+## TUI
+
+- **Composer strip** (`session.composer.top`): `📋 ███░░░░░ 8/17 open` (plus `⏸`
+  while paused), hidden when there is neither a list nor a subscription.
+- **Popover** (`/todos`, palette "Todo: open todos"): a centered overlay dialog.
+  The body is height-bounded (up to 16 rows) so the key legend is always visible;
+  the header shows `open/total` and the selected `row n/m`. `f` cycles the dialog
+  size (medium → large → xlarge), `esc` closes it.
+  - header: progress bar, `open/total`, and a supervision chip (`idle · quiet
+    12s · nudges 2`, `working: 1 tool · 1 shell · quiet 4s`, `paused
+    (no-progress)`, `not supervised`);
+  - body: a `SESSION` section, then one collapsible section per subscribed file
+    (`n open of m`, `(missing)` badge, `:line` refs);
+  - keys: `↑↓`/`jk` move, `pgup`/`pgdn`, `home`/`end`/`g`/`G`, `space`/`x` toggle
+    (session item, markdown item, or collapse a file row), `enter` collapse, `n`
+    nudge now, `s` pause/resume, `a` add file, `d` remove file, `r` refresh, `/`
+    filter, `f` resize, `c` clear (confirm), `?` help, `escape` close;
+  - it re-reads every 3 s while open, so edits made outside OpenCode show up
+    without waiting for an event.
+- **Side panel** (palette "Todo: open side panel"): the same list docked to
+  `session.panel` (`todo.todos`), with `f` for fullscreen.
+- `/todos add <path>` and `/todos remove <path>` manage subscriptions from the
+  prompt.
+- **Toasts** on `nudged` (idle vs stalled wording) and on the all-done transition.
+
+## Commands
+
+| Where | Command | Effect |
+| --- | --- | --- |
+| Slash | `/todos` | Open the todo popover for the current session |
+| Slash | `/todos add <path>` | Subscribe a markdown file |
+| Slash | `/todos remove <path>` | Unsubscribe a markdown file |
+| Palette | `Todo: open todos` | Same as `/todos` |
+| Palette | `Todo: open side panel` | Dock the list to `session.panel` instead of the popover |
+
+## RPC
+
+Contract id `todo` (`opencode-todo-supervisor/rpc`). The TUI uses
+`context.client.rpc(TodoRpc)` and `rpc.events.on(...)`.
+
+| Method | Input | Purpose |
+| --- | --- | --- |
+| `list` | `{ sessionID }` | Items, subscribed files (parsed fresh), and the supervisor snapshot |
+| `clear` | `{ sessionID }` | Drop the stored list (subscriptions stay) |
+| `nudge` | `{ sessionID }` | Send a nudge now (same dedupe/ownership rules as automatic nudges) |
+| `setEnabled` | `{ sessionID, enabled }` | Per-session supervision kill switch |
+| `toggle` | `{ sessionID, index }` | Flip one session item between completed and pending |
+| `toggleFile` | `{ sessionID, path, line }` | Toggle a checklist item inside a subscribed markdown file |
+| `subscribe` | `{ sessionID, path }` | Subscribe a markdown file |
+| `unsubscribe` | `{ sessionID, path }` | Shadow a subscription |
+
+Events: `updated` (`{ sessionID }`) and `nudged` (`{ sessionID, reason }`).
+
+Over HTTP (service credentials required):
+
+```bash
+opencode2 api post /api/rpc/todo/list \
+  -H 'content-type:application/json' \
+  -d '{"input":{"sessionID":"ses_…"}}'
+# → {"output": { items, files, supervisor }}
+```
+
+The body/response are wrapped in `{ "input": … }` / `{ "output": … }`.
+
+## Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch for supervision (tools keep working) |
+| `settleMs` | `5000` | Debounce after a **confirmed end of turn** before the idle nudge |
+| `minNudgeIntervalMs` | `45000` | Minimum gap between two nudges for one session |
+| `stallMinutes` | `5` | With any work in flight: minutes of silence before a *stall* nudge |
+| `maxNoProgressNudges` | `5` | Consecutive nudges with an unchanged open-item set before backing off |
+| `injectTodoContext` | `true` | Append the current list to every model request (survives compaction) |
+| `markdownFiles` | `[]` | Markdown checklists auto-subscribed for sessions in the project |
+| `scope` | `"project"` | Only supervise sessions of the plugin's own project (`"project"` or `"all"`) |
+| `pauseOnInterrupt` | `true` | Pause supervision after an interrupted execution until the user continues |
+| `debugEvents` | `false` | Log the raw event stream |
+
+## How it works
+
+One server plugin instance runs per OpenCode location. It registers the todo
+tools, subscribes to the session event stream to supervise activity, injects the
+current list into each model request, and exposes an RPC contract that the TUI
+reads.
+
+### Event-driven supervision
+
+The supervisor subscribes to the public event stream and keeps a per-session
+state machine in memory (`src/supervisor.ts`). It does **not** trust a session
+"status" flag — this runtime does not reliably emit one. Instead it tracks
+**activity spans**: anything the runtime is currently doing, opened by a
+`*.started` (or `.called`) event and closed by its matching
+`*.ended`/`.success`/`.failed`:
+
+| Doing | Opened by | Closed by |
+| --- | --- | --- |
+| turn | `execution.started` | `execution.succeeded/failed/interrupted`, `status idle` |
+| step | `step.started` | `step.ended` (with `finish`, see below) |
+| thinking | `reasoning.started` | `reasoning.ended` |
+| writing | `text.started` | `text.ended` |
+| preparing a tool | `tool.input.started` | `tool.input.ended` |
+| running a tool (`task`, `shell`, …) | `tool.input.started`/`tool.called` | `tool.success`/`failed` |
+| background shell | `shell.created` | `shell.exited`/`deleted` |
+| queued input | `inbox.enqueued` | `inbox.delivered` |
+
+A session is idle **only when nothing is open** — no span, no in-flight tool
+call, no background shell, no still-busy child, no queued inbox item. A step that
+ends with `finish:"tool-calls"` means "the turn continues" and never arms a
+nudge; a step ending with `finish:"stop"`, an execution `succeeded/failed/
+interrupted`, or a `status idle` is a **confirmed end of turn** (`endTurn()`),
+which also heals spans whose close event was lost (an interrupt or a reload
+mid-call).
+
+### `evaluate(sessionID)`
+
+On every relevant event the supervisor (re)arms a per-session timer and
+recomputes from current state:
+
+1. if there is nothing open in any source, or supervision is paused/blocked →
+   stop;
+2. if work is in flight (spans, tools, shells, busy children), measure the quiet
+   time — schedule a re-check if it is under `stallMinutes`, otherwise send a
+   **stall nudge** naming what is quiet;
+3. if nothing is open, wait for the debounce — `settleMs` after a confirmed turn
+   end, or the more conservative `stallMinutes` if no end-of-turn signal was ever
+   seen — then send an **idle nudge**.
+
+### Nudging
+
+Nudges go out through `ctx.session.synthetic({ sessionID, text, description,
+metadata })`, so the model receives them as ordinary instructions rather than a
+visible user turn. Each nudge:
+
+- carries the counts, the open items (with priorities), and an explainer — e.g.
+  `Idle nudge #2 — the session went idle with 3 of 7 todos left.` or
+  `Stall nudge #1 — no activity for ~7.2 min from: subagent ses_… / background
+  shell "sleep 200" / tool subagent "Add the panel" / open step (stall threshold
+  5 min).`;
+- is rate-limited (`minNudgeIntervalMs`) and de-duplicated by an open-item hash;
+- backs off after `maxNoProgressNudges` nudges with an unchanged list and resumes
+  on the next `todo_write` (the panel's `s` can pause/resume too).
+
+**Output counts as progress, not just events.** A shell/task writes its stdout to
+a capture file, and appending to it emits no plugin event at all — so the
+supervisor stats each tracked shell's capture (`shell.created.info.file`) and uses
+its mtime as activity. A task that keeps printing is never "stalled", no matter
+how few events it produces. The quiet clock is also **transitive**: a parent
+includes the shells and tools of its still-busy children, and a child stops
+counting once it has ended its turn.
+
+### Context injection
+
+On every model request (`ctx.session.hook("context")`) the plugin appends a
+compact system block with the current list and a one-line policy. This is read
+from an in-memory cache (kept fresh by tool writes and scans), so it adds no async
+work per call — and it **survives compaction**: even if the `todo_write` history
+is summarized away, the list is re-injected on the next request.
+
+### Storage
+
+A thin wrapper over `ctx.storage` (durable JSON scoped to the plugin):
+
+| Key | Value |
+| --- | --- |
+| `todos/<sessionID>` | `{ version, sessionID, items[], updatedAt }` |
+| `subs/<sessionID>` | `{ version, sessionID, files[], removed[], updatedAt }` |
+| `claims/<sessionID>` | `{ tag, at }` — hot-reload ownership |
+
+On startup the plugin scans `todos/` and reconciles against `ctx.session.get()`
+(session gone → drop the entry; session alive → register and evaluate once).
+Supervision counters (nudge counts, no-progress, pause) are in-memory only; a
+restart resets them, which is deliberate and simpler. Sessions are dropped on
+`session.deleted`.
+
+### Hot reloads
+
+The runtime may load a new plugin generation before disposing the old one. Every
+registration writes an **ownership claim** (`claims/<sessionID> = { tag, at }`),
+and a nudge is only sent when no strictly newer claim exists — so exactly one
+generation of the plugin nudge a given session, even while two are alive.
+The event loop also stops as soon as its abort signal fires.
+
+### Freshness
+
+There is no filesystem watcher. Instead:
+
+- `evaluate()`, RPC `list` and `todo_read` re-parse subscribed files fresh;
+- a `ctx.tool.hook("execute.after")` re-parses immediately when an
+  `edit`/`write`/`patch` touches a subscribed file and emits RPC `updated`;
+- the open panel polls every 3 s.
+
+## Development
+
+- Edit any file in this directory → the running service hot-reloads the plugin
+  (source edits and config content changes; `touch` alone does not).
+- `opencode2 reload` forces reconciliation; `opencode2 service restart` only as a
+  last resort (it interrupts sessions).
+- Tests: `bun test` (106 tests across parser, storage, tools, RPC, state machine,
+  panel helpers).
+- Watch logs: `tail -f ~/.local/share/opencode/log/todo-supervisor.log`.
+
+## Limitations
+
+- The TUI panel/keyboard actions and toasts need a running TUI; the strip counts
+  refresh on RPC `updated` (i.e. immediately after `todo_write`).
+- Markdown write-back edits your files: `x` on a markdown row rewrites that
+  checkbox in place (temp file + atomic rename, only for subscribed paths). Use
+  the panel filter and `d` if you only want to read.
+- `pauseOnInterrupt` relies on the execution-interrupted event: after an
+  interrupt, supervision resumes on the next `todo_write`/status event.
+- No filesystem watcher: external edits are picked up at the next evaluation, the
+  next UI read, or the panel's 3 s poll (see Freshness).
+- Subscription reads can briefly lag across roles right after a write;
+  supervision and the UI re-read per call and are unaffected.
+- Runtimes that never emit an end-of-turn signal fall back to the `stallMinutes`
+  window for idle nudges (see `evaluate`).
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,3 @@
+// Root-level shim so this directory works as a discovery-style plugin package
+// (see PLAN.md §7 fallback ladder, rung 3). The real implementation lives in src/.
+export { default } from "./src/index"

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@hacky.software/opencode-todo-supervisor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "OpenCode V2 plugin that gives every session a todo list (todo_write/todo_read), supervises idle sessions until the list is done, and can drive checklists in markdown files from a TUI panel.",
+  "type": "module",
+  "license": "MIT",
+  "author": "n0k0",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "todo",
+    "todos",
+    "checklist",
+    "supervisor",
+    "tui",
+    "markdown"
+  ],
+  "homepage": "https://github.com/N0K0/opencode-todo-supervisor#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/N0K0/opencode-todo-supervisor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/N0K0/opencode-todo-supervisor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./rpc": "./src/rpc.ts",
+    "./tui": "./src/tui.tsx"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "tui.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.0.24"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.14",
+    "@opentui/solid": ">=0.5.14",
+    "solid-js": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+// todo-supervisor — OpenCode V2 server plugin.
+//
+// Aspect 1 (scaffold & loading) done: registers, logs setup/unload, options
+// flow. Aspect 2 wired the raw event stream behind `debugEvents` for payload
+// verification. Aspects 3–5 added options parsing, storage and the todo tools.
+// Aspect 6+ wires the event stream into the supervisor state machine
+// (src/supervisor.ts, PLAN.md §5.4).
+//
+// Hot-reload note: the runtime may start a new plugin generation before/without
+// disposing the old one. Every instance therefore gets a unique tag, the event
+// loop stops as soon as its abort signal fires, cleanup is idempotent and the
+// supervisor uses storage ownership claims to make duplicate nudges impossible.
+import { basename } from "node:path"
+import { Plugin } from "@opencode/plugin"
+import { log } from "./log"
+import { MarkdownCache } from "./markdown"
+import { parseOptions } from "./options"
+import { registerTodoRpc } from "./rpc"
+import { makeStore } from "./storage"
+import { normalizeEvent, Supervisor, truncate } from "./supervisor"
+import { makeContextInjector, registerExecuteAfterHook, registerTools } from "./tools"
+
+// Module-level probe: if this counter keeps growing across reloads, plugin
+// generations share one module instance (a truth we want to know).
+let moduleLoads = 0
+let instanceSeq = 0
+
+export default Plugin.define({
+  id: "todo-supervisor",
+  async setup(ctx) {
+    const options = parseOptions(ctx.options)
+    const tag = `${basename(ctx.location.directory)}#${++instanceSeq}@${Math.random().toString(36).slice(2, 6)}`
+    const instanceLog = (...args: unknown[]) => log(`(${tag})`, ...args)
+
+    instanceLog(`module load #${++moduleLoads}`)
+    instanceLog(`setup — OpenCode ${ctx.app.version} · location=${ctx.location.directory} · project=${ctx.location.project.id}`)
+    instanceLog(`options: ${JSON.stringify(options)}`)
+
+    const store = makeStore(ctx.storage)
+    const markdown = new MarkdownCache()
+    // RPC events (aspect 11): the emitter is swapped in once the registration
+    // exists; until then (and if registration fails) it is a no-op.
+    let rpcEmit: (name: "updated" | "nudged", payload: Record<string, unknown>) => void = () => {}
+    const supervisor = new Supervisor({
+      options,
+      store,
+      projectID: ctx.location.project.id,
+      tag,
+      log: instanceLog,
+      emitRpcEvent: (name, payload) => rpcEmit(name, payload),
+      markdown,
+      directory: ctx.location.directory,
+      synthetic: async (input) => {
+        await ctx.session.synthetic(input)
+      },
+      getSession: async (sessionID) => {
+        const info = await ctx.session.get({ sessionID })
+        return { projectID: info.projectID, parentID: info.parentID }
+      },
+      claims: ctx.storage,
+    })
+
+    const tools = await registerTools(ctx, store, {
+      log: instanceLog,
+      onTodosChanged(sessionID) {
+        supervisor.notifyTodosChanged(sessionID)
+        rpcEmit("updated", { sessionID })
+      },
+    }, options, { markdown, directory: ctx.location.directory })
+
+    // Context injection (§5.5, aspect 10): a system block on every model request.
+    let contextRegistration: { dispose(): Promise<void> } | undefined
+    try {
+      const injector = makeContextInjector(store, options, instanceLog)
+      contextRegistration = await ctx.session.hook("context", (event) => injector(event))
+      instanceLog(`context hook registered (injectTodoContext=${options.injectTodoContext})`)
+    } catch (err) {
+      instanceLog(`context hook registration failed: ${String(err)}`)
+    }
+
+    // RPC (§5.6, aspect 11): contract registration + event emitter.
+    let rpcRegistration: { dispose(): Promise<void> } | undefined
+    try {
+      const reg = await registerTodoRpc(ctx, {
+        store,
+        supervisor,
+        options,
+        markdown,
+        directory: ctx.location.directory,
+        log: instanceLog,
+      })
+      rpcRegistration = reg
+      rpcEmit = (name, payload) => reg.emit(name, payload)
+      instanceLog("rpc registered (todo.list/clear/nudge/setEnabled/toggle/toggleFile/subscribe/unsubscribe)")
+    } catch (err) {
+      instanceLog(`rpc registration failed: ${String(err)}`)
+    }
+
+    // Markdown refresh on edits of subscribed files (§5.8, aspect 14c).
+    let toolHookRegistration: { dispose(): Promise<void> } | undefined
+    try {
+      toolHookRegistration = await registerExecuteAfterHook(ctx, {
+        store,
+        markdown,
+        options,
+        directory: ctx.location.directory,
+        onChanged: (sessionID) => {
+          supervisor.notifyTodosChanged(sessionID)
+          rpcEmit("updated", { sessionID })
+        },
+        log: instanceLog,
+      })
+      instanceLog("execute.after hook registered (markdown refresh)")
+    } catch (err) {
+      instanceLog(`execute.after hook registration failed: ${String(err)}`)
+    }
+
+    const ac = new AbortController()
+    void runEventLoop(ctx, supervisor, instanceLog, { debugEvents: options.debugEvents }, ac.signal)
+
+    // Startup reconcile: adopt stored lists whose sessions still exist (§5.4).
+    void supervisor
+      .reconcile()
+      .catch((err) => instanceLog(`reconcile failed: ${String(err)}`))
+
+    let cleaned = false
+    return async () => {
+      if (cleaned) return
+      cleaned = true
+      instanceLog("cleanup — disposing supervisor")
+      ac.abort()
+      supervisor.dispose()
+      await tools.dispose()
+      if (contextRegistration) {
+        try {
+          await contextRegistration.dispose()
+        } catch (err) {
+          instanceLog(`context hook dispose failed: ${String(err)}`)
+        }
+      }
+      if (rpcRegistration) {
+        try {
+          await rpcRegistration.dispose()
+        } catch (err) {
+          instanceLog(`rpc dispose failed: ${String(err)}`)
+        }
+      }
+      if (toolHookRegistration) {
+        try {
+          await toolHookRegistration.dispose()
+        } catch (err) {
+          instanceLog(`execute.after hook dispose failed: ${String(err)}`)
+        }
+      }
+      instanceLog("unloaded")
+    }
+  },
+})
+
+async function runEventLoop(
+  ctx: Plugin.Context,
+  supervisor: Supervisor,
+  instanceLog: (...args: unknown[]) => void,
+  opts: { debugEvents: boolean },
+  signal: AbortSignal,
+): Promise<void> {
+  instanceLog("event loop started")
+  try {
+    for await (const raw of ctx.event.subscribe({ signal })) {
+      if (signal.aborted) break
+      try {
+        if (opts.debugEvents) {
+          const event = normalizeEvent(raw)
+          if (event) instanceLog(`event ${event.type}`, truncate(JSON.stringify(event.data)))
+        }
+        // supervisor.handle swallows per-event errors by design (§11, Aspect 6).
+        await supervisor.handle(raw)
+      } catch (err) {
+        instanceLog("event handler error", String(err))
+      }
+    }
+    instanceLog(`event loop ended (aborted=${signal.aborted})`)
+  } catch (err) {
+    instanceLog(`event loop failed (aborted=${signal.aborted})`, String(err))
+  }
+}