trekoon 0.4.2 → 0.4.3

package/.agents/skills/trekoon/reference/sync.md

@@ -1,129 +1,82 @@
 # Sync Reference
 
-## Sync reminders
+Trekoon uses one live SQLite database per repository at
+`<sharedStorageRoot>/.trekoon/trekoon.db`. Linked worktrees share it. `git
+checkout` and `git switch` do not roll back tracker state. Sync imports tracker
+events between branches; never copy or commit the `.db` file.
 
-Same-branch sync is a no-op: `sync pull --from main` while on `main` produces
-zero conflicts and simply advances the cursor. `sync status` returns `behind=0`
-on the source branch. No action is needed.
+Same-branch sync is a no-op. Cross-branch sync matters before merging a feature
+branch back.
 
-Cross-branch sync matters before merging a feature branch back:
+## Before Merge
 
-- Before merge, pull tracker events from the base branch:
+Pull tracker events from the base branch:
 
-  ```bash
-  trekoon --toon sync pull --from main
-  ```
-
-- If conflicts exist, inspect and resolve them explicitly:
+```bash
+trekoon --toon sync pull --from main
+```
 
-  ```bash
-  trekoon --toon sync conflicts list
-  trekoon --toon sync conflicts show <conflict-id>
-  trekoon --toon sync resolve <conflict-id> --use theirs --dry-run
-  trekoon --toon sync resolve <conflict-id> --use ours
-  ```
+If conflicts exist:
 
-### Conflict resolution: ours vs theirs
+```bash
+trekoon --toon sync conflicts list
+trekoon --toon sync conflicts show <conflict-id>
+trekoon --toon sync resolve <conflict-id> --use theirs --dry-run
+trekoon --toon sync resolve <conflict-id> --use ours
+```
 
-Conflicts are **field-level**, not whole-record. Each conflict targets one field
-(e.g., `status`, `title`, `description`) on one entity.
+## Conflict Rules
 
-- `--use ours` — keep the current entity field value in the shared DB. The
-  entity is not written, but the conflict record is marked resolved and a
-  resolution event is appended.
-- `--use theirs` — overwrite the shared DB entity field with the source-branch
-  value. The conflict record is marked resolved and a resolution event is
-  appended.
-- `--dry-run` — preview the resolution without mutating the database. Returns
-  `oursValue`, `theirsValue`, `wouldWrite`, and `dryRun: true`. Use this before
-  committing to a resolution.
+Conflicts are field-level, not whole-record. Each conflict targets one field on
+one entity.
 
-**Example:** after `sync pull --from main`, a conflict appears on epic `abc123`,
-field `status`:
-- ours (current DB): `in_progress`
-- theirs (source branch): `done`
-- `--use ours` keeps status as `in_progress`
-- `--use theirs` changes status to `done` in the live shared DB
+- `--use ours`: keep the current shared DB field value; mark conflict resolved.
+- `--use theirs`: write the source-branch field value into the shared DB; mark
+  conflict resolved.
+- `--dry-run`: preview without mutation. Returns `oursValue`, `theirsValue`,
+  `wouldWrite`, and `dryRun: true`.
 
-Always inspect conflicts with `sync conflicts show` before resolving. Choosing
-`theirs` without inspection can overwrite in-progress work in the shared DB.
+Always inspect with `sync conflicts show` before resolving. Choosing `theirs`
+without inspection can overwrite in-progress shared DB work.
 
-### Understanding why conflicts happen
+Typical choices:
 
-| Scenario | Typical resolution | Why |
+| Scenario | Usually use | Why |
 |---|---|---|
-| Completed work vs stale main state | ours | Your branch has the latest progress |
+| Completed work vs stale main | ours | Your branch has latest progress |
 | Enriched descriptions vs original | ours | Your descriptions are more detailed |
-| Upstream updates from another agent | theirs | Accept the newer upstream state |
-| User-intentional reset | theirs | Respect the user's explicit action |
+| Upstream updates from another agent | theirs | Accept newer upstream state |
+| User-intentional reset | theirs | Respect explicit user action |
 
-### Agent decision framework
+When unsure, ask the user.
 
-1. List conflicts: `trekoon --toon sync conflicts list`
-2. Group by pattern — are conflicts on the same field or direction?
-3. If uniform pattern, batch resolve: `trekoon --toon sync resolve --all --use ours`
-4. If mixed, narrow by entity or field, or inspect individually
-5. When unsure, ask the user
-
-### Batch resolve patterns
-
-Common scenarios:
+## Batch Resolve
 
 ```bash
-# Resolve all conflicts at once (most common after completing work)
-trekoon --toon sync resolve --all --use ours
-
-# Preview before resolving
 trekoon --toon sync resolve --all --use ours --dry-run
-
-# Narrow to status field conflicts only
+trekoon --toon sync resolve --all --use ours
 trekoon --toon sync resolve --all --use ours --field status
-
-# Narrow to a specific entity
 trekoon --toon sync resolve --all --use theirs --entity <id>
-
-# Combine filters
 trekoon --toon sync resolve --all --use ours --entity <id> --field description
 ```
 
-## Shared-database model
-
-Trekoon uses **one live SQLite database per repository**. The file lives at
-`<sharedStorageRoot>/.trekoon/trekoon.db`, where `sharedStorageRoot` is the
-parent of `git rev-parse --git-common-dir` (i.e., the main worktree root).
-
-Key consequences:
-
-- **All linked worktrees share the same database.** A status change in one
-  worktree is immediately visible in every other worktree.
-- **`git checkout` / `git switch` does not change tracker state.** The database
-  is outside the git object store, so switching branches does not roll back or
-  swap task data.
-- **Sync operates on tracker events, not on the database file itself.** Use
-  `sync pull` to import events between branches — never copy or commit the
-  `.db` file.
-
-Treat every write as a mutation of shared repo-wide state, not branch-scoped
-state.
-
-**Conflicts are scoped per worktree + branch.** `sync_conflicts` rows are
-recorded with the originating worktree path and current branch, so resolving a
-conflict in one worktree never erases a peer worktree's conflict on the same
-entity. `sync conflicts list` and `sync resolve` from a given worktree only
-see and act on rows scoped to that worktree's branch.
-
-## Worktree diagnostics and destructive scope
-
-- Inspect machine-readable storage fields when debugging worktrees:
-  `storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`, and
-  `databaseFile`.
-- `sharedStorageRoot` is the repo-scoped source of truth for `.trekoon` in git
-  worktrees.
-- If `trekoon wipe --yes --toon` is explicitly requested, warn that it deletes
-  shared storage for the entire repository and every linked worktree.
-- Wipe is destructive recovery only; it is never the right fix for a tracked DB
-  or gitignore mistake.
-
-Trekoon stores local state in `.trekoon/trekoon.db`. In git repos and
-worktrees, storage resolves from the shared repository root rather than each
-worktree independently.
+Use batch resolve only when the conflict pattern is uniform. Otherwise inspect
+and resolve individually or narrow by `--entity` / `--field`.
+
+## Worktree Scope
+
+Inspect machine-readable storage fields when debugging worktrees:
+`storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`, and
+`databaseFile`.
+
+Conflicts are scoped per worktree and branch. `sync conflicts list` and
+`sync resolve` only act on rows for the current worktree/branch, so resolving a
+conflict does not erase a peer worktree's conflict on the same entity.
+
+## Destructive Recovery
+
+`sharedStorageRoot` is the repo-scoped source of truth for `.trekoon` in git
+worktrees. If the user explicitly requests `trekoon wipe --yes --toon`, warn
+that it deletes shared storage for the whole repository and every linked
+worktree. Wipe is destructive recovery only; it is never the fix for a tracked
+DB or gitignore mistake.

package/README.md

@@ -90,8 +90,8 @@ What the agent does during execution:
    calls `task done`
 6. `task done` returns which downstream tasks just became unblocked, so the
    orchestrator knows what to dispatch next
-7. After all tasks complete: code review, tests, manual verification, then marks
-   the epic `done`
+7. After all tasks complete: review agent or review skill for non-trivial
+   changes, tests, manual verification, then marks the epic `done`
 
 The orchestrator uses `task done` responses to drive the whole loop. No polling,
 no guessing. When a task finishes, Trekoon tells you exactly what's ready next.
@@ -110,13 +110,15 @@ agents don't know how to use Trekoon properly.
 ```bash
 trekoon skills install          # repo-local (.agents/skills/trekoon/)
 trekoon skills install -g       # global (~/.agents/skills/trekoon)
+trekoon skills install --link --editor codex    # editor link (.codex/skills/trekoon)
 trekoon update                  # refresh all installed skills
 ```
 
-The skill bundles three reference documents that agents load on demand:
+The skill bundles reference documents that agents load on demand:
 
 | Agent needs to... | Skill reads | What it covers |
 | --- | --- | --- |
+| Coordinate across harnesses | `reference/harness-primitives.md` | Universal subagent, question, local task display, review, and evidence-recording guidance |
 | Plan a feature | `reference/planning.md` | Decomposition, writing standard, dependency modeling, validation |
 | Execute an epic | `reference/execution.md` | Graph building, lane grouping, sub-agent dispatch, verification (universal) |
 | Execute with Agent Teams | `reference/execution-with-team.md` | TeamCreate/SendMessage, parallel Claude Code instances in tmux |
@@ -145,6 +147,16 @@ Execute only:
 /trekoon <epic-id> execute
 ```
 
+When you execute an epic, use subagents by default for any meaningful work that
+can run independently. Keep small or tightly coupled tasks in the parent agent.
+Use the main context for orchestration, dependency decisions, user
+communication, and final synthesis while Trekoon remains the durable source of
+truth.
+
+If a harness has a higher-priority rule requiring explicit permission before
+subagents, surface that immediately instead of silently doing broad work
+yourself.
+
 Plan and execute end to end:
 
 ```
@@ -154,9 +166,11 @@ dependency order until the epic is complete
 
 ## Agent Teams
 
-For larger epics, Trekoon supports Claude Code Agent Teams. Instead of
-sequential sub-agents, you get real parallel Claude Code instances coordinated
-through `TeamCreate` and `SendMessage`, each running in its own tmux pane.
+For larger epics, use the current harness's native subagent mechanism for
+meaningful work that can run independently. Claude Code Agent Teams are one
+runtime-specific option: instead of sequential sub-agents, you get real parallel
+Claude Code instances coordinated through `TeamCreate` and `SendMessage`, each
+running in its own tmux pane.
 
 Requires Claude Code env variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`.
 
@@ -201,7 +215,7 @@ shell, worktree, or browser tab show up live without a manual refresh.
 | --- | --- |
 | Set up a repo | `trekoon init` |
 | Open the local board | `trekoon board open` |
-| Plan work | `trekoon epic create ...`, `trekoon epic expand ...` |
+| Plan work | `trekoon --toon epic create ...`, `trekoon --toon epic expand ...` |
 | Create tasks in bulk | `trekoon task create-many ...` |
 | Add dependencies | `trekoon dep add-many ...` |
 | Start an agent session | `trekoon session --epic <id>` |

package/docs/ai-agents.md

@@ -14,22 +14,39 @@ agent to:
 - append progress and blocker notes instead of rewriting descriptions
 - preview scoped replace before `--apply`
 - treat `.trekoon` as shared repo-scoped state
+- use harness-local todo/task tools as a live progress display while keeping
+  Trekoon as the durable source of truth
+- use subagents by default for meaningful work that can run independently when
+  the harness exposes them
+- keep small or tightly coupled tasks in the parent agent so the main context
+  stays available for orchestration and decisions
 
 The skill ships with reference guides so the agent can handle the full
 plan-to-completion workflow from one install:
 
 ```
 .agents/skills/trekoon/
-  SKILL.md                      <- command reference, status machine, agent loop
+  SKILL.md                      <- command router and operating contract
   reference/
+    harness-primitives.md       <- universal agent/task/question/review primitives
     planning.md                 <- decomposition, writing standard, validation
     execution.md                <- graph building, lane dispatch, verification
     execution-with-team.md      <- Agent Teams pattern (Claude Code only)
 ```
 
-The agent loads the relevant reference on demand: `planning.md` when asked to
-plan, `execution.md` when asked to execute, `execution-with-team.md` when Agent
-Teams are available.
+The command shape determines what the agent loads:
+
+| User command | Required references |
+| --- | --- |
+| `/trekoon plan <goal>` | `harness-primitives.md`, then `planning.md` |
+| `/trekoon <id>` | `SKILL.md` only, unless deeper analysis is needed |
+| `/trekoon <id> analyze` | `SKILL.md` plus targeted Trekoon reads |
+| `/trekoon <id> execute` | `harness-primitives.md`, then `execution.md` |
+| `/trekoon <id> team execute` | `harness-primitives.md`, then `execution-with-team.md` |
+
+`harness-primitives.md` is loaded before planning or execution because those
+modes may need structured questions, local progress displays, subagent
+delegation, review agents, and runtime-specific orchestration.
 
 ## Install the skill
 
@@ -42,6 +59,7 @@ Create a project-local editor link when your agent environment supports it:
 ```bash
 trekoon skills install --link --editor opencode
 trekoon skills install --link --editor claude
+trekoon skills install --link --editor codex
 trekoon skills install --link --editor pi
 trekoon skills install --link --editor opencode --to ./.custom-editor/skills
 trekoon skills update
@@ -52,6 +70,7 @@ Path behavior:
 - Canonical install: `.agents/skills/trekoon/SKILL.md`
 - OpenCode link: `.opencode/skills/trekoon`
 - Claude link: `.claude/skills/trekoon`
+- Codex link: `.codex/skills/trekoon`
 - Pi link: `.pi/skills/trekoon`
 - `--to <path>` changes only the editor link root
 - `--allow-outside-repo` is for intentional external links
@@ -97,6 +116,17 @@ Typical flow:
 
 The core loop: **session, work, task done, repeat**.
 
+When you execute an epic, use subagents by default for any meaningful work that
+can run independently. Keep small or tightly coupled tasks in the parent agent.
+Build the Trekoon execution graph, group ready tasks into lanes, keep a local
+todo/task display for the user, and synthesize the results. Use the parent
+context for dependency decisions and finishing the epic.
+
+Some harnesses have higher-priority rules that require explicit user permission
+before spawning subagents. When that happens, say so immediately after
+discovering independent lanes and ask for permission before broad execution. Do
+not silently default to single-agent execution.
+
 Start with a single orientation call, optionally scoped to an epic:
 
 ```bash
@@ -193,6 +223,20 @@ notes, mark it done, and repeat until there are no ready tasks or you hit a
 blocker.
 ```
 
+### Execute with subagents where useful
+
+```text
+/trekoon <epic-id> execute -- use subagents by default for meaningful work that
+can run independently, keep Trekoon as the source of truth, and use local task
+tools to show live progress.
+```
+
+Short form for harnesses that require explicit delegation wording:
+
+```text
+/trekoon <epic-id> execute with subagents
+```
+
 ### Plan and execute end to end
 
 ```text

package/docs/commands.md

@@ -22,8 +22,8 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 - `trekoon sync resolve <conflict-id> --use ours|theirs [--dry-run]`
 - `trekoon sync resolve --all --use ours|theirs [--entity <id>] [--field <name>] [--dry-run]`
 - `trekoon sync conflicts <list|show> [--mode pending|all]`
-- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]`
-- `trekoon skills install -g|--global [--editor opencode|claude|pi]`
+- `trekoon skills install [--link --editor opencode|claude|codex|pi] [--to <path>] [--allow-outside-repo]`
+- `trekoon skills install -g|--global [--editor opencode|claude|codex|pi]`
 - `trekoon skills update`
 - `trekoon wipe --yes`
 - `trekoon serve` (experimental)

package/docs/quickstart.md

@@ -69,7 +69,7 @@ if you just need to refresh the runtime assets without opening the browser.
 ## Create work
 
 ```bash
-trekoon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
+trekoon --toon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
 trekoon task create --title "Implement sync status" --description "Add status reporting" --epic <epic-id> --status todo
 trekoon subtask create --task <task-id> --title "Add cursor model" --status todo
 ```
@@ -88,7 +88,7 @@ trekoon task list --all --view compact
 If you already know the full epic tree, create everything in one call:
 
 ```bash
-trekoon epic create \
+trekoon --toon epic create \
   --title "Batch command rollout" \
   --description "Ship one-shot planning workflows" \
   --task "task-a|First task|First description|todo" \
@@ -118,7 +118,7 @@ For larger updates, use batch commands instead of looping:
 | Multiple tasks under one epic | `trekoon task create-many --epic <epic-id> --task ...` |
 | Multiple subtasks under one task | `trekoon subtask create-many <task-id> --subtask ...` |
 | Multiple dependency edges | `trekoon dep add-many --dep ...` |
-| Expand an existing epic | `trekoon epic expand <epic-id> ...` |
+| Expand an existing epic | `trekoon --toon epic expand <epic-id> ...` |
 
 These validate the whole batch before applying, so a bad input fails the entire
 operation instead of leaving partial state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "AI-first task tracking that lives in your repo. You describe what to build, your agent plans it as a dependency graph, then executes it task by task",
   "keywords": [
     "ai",

package/src/board/assets/app.js

@@ -479,9 +479,11 @@ export async function bootLegacyBoard(options = {}) {
       rerender,
     });
     if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
-      window.addEventListener("beforeunload", () => {
+      const disposeSnapshotSubscription = () => {
         snapshotSubscription.dispose();
-      }, { once: true });
+      };
+      window.addEventListener("beforeunload", disposeSnapshotSubscription, { once: true });
+      window.addEventListener("pagehide", disposeSnapshotSubscription, { once: true });
     }
 
     // Actions for delegation

package/src/board/assets/components/Component.js

@@ -153,8 +153,8 @@ export function preserveFormState(container, writeFn, options = {}) {
 
   // Per-form cache for getManagedControls: avoids the O(n^2) re-query that
   // occurs when many controls share the same form root.
-  const captureCache = new Map();
-  const inputs = getManagedControls(container, captureCache);
+  const controlCache = new Map();
+  const inputs = getManagedControls(container, controlCache);
 
   const activeElement = document.activeElement;
   let focusedIdentity = null;
@@ -162,7 +162,7 @@ export function preserveFormState(container, writeFn, options = {}) {
   const savedStates = inputs.map((el) => {
     const form = getFormRoot(el);
     const formId = getNamespacedFormIdentity(form);
-    const controlId = form ? getControlIdentity(el, form, captureCache) : null;
+    const controlId = form ? getControlIdentity(el, form, controlCache) : null;
     const identity = controlId ? { formId, controlId } : null;
 
     if (activeElement === el) {
@@ -180,6 +180,7 @@ export function preserveFormState(container, writeFn, options = {}) {
   }).filter(s => s.identity);
 
   writeFn();
+  controlCache.clear();
 
   const formsByIdentity = new Map(
     Array.from(container.querySelectorAll(FORM_ROOT_SELECTOR)).map((form) => [
@@ -188,16 +189,13 @@ export function preserveFormState(container, writeFn, options = {}) {
     ]),
   );
 
-  // Fresh cache for the restore pass (DOM was replaced by writeFn).
-  const restoreCache = new Map();
-
   for (const state of savedStates) {
     const { formId, controlId } = state.identity;
     if (resetFormIds.has(formId)) {
       continue;
     }
     const form = formsByIdentity.get(formId) ?? container;
-    const restored = getManagedControls(form, restoreCache).find((control) => getControlIdentity(control, form, restoreCache) === controlId);
+    const restored = getManagedControls(form, controlCache).find((control) => getControlIdentity(control, form, controlCache) === controlId);
     if (restored && restored.value !== state.value) {
       restored.value = state.value;
     }
@@ -213,7 +211,7 @@ export function preserveFormState(container, writeFn, options = {}) {
       return;
     }
     const form = formsByIdentity.get(formId) ?? container;
-    const restored = getManagedControls(form, restoreCache).find((control) => getControlIdentity(control, form, restoreCache) === controlId);
+    const restored = getManagedControls(form, controlCache).find((control) => getControlIdentity(control, form, controlCache) === controlId);
     if (restored) {
       restored.focus({ preventScroll: true });
       const focusedState = savedStates.find((state) => state.identity?.formId === formId && state.identity?.controlId === controlId);

package/src/board/assets/state/actions.js

@@ -444,6 +444,9 @@ export function createBoardActions(options) {
       const nextKey = feedback ? `${feedback.targetStatus}|${feedback.kind}` : null;
       if (prevKey === nextKey) return;
       store.dragFeedback = feedback;
+      if (typeof model.invalidateBoardStateMemo === "function") {
+        model.invalidateBoardStateMemo();
+      }
       rerender();
     },
     dropTaskStatus(taskId, nextStatus) {

package/src/board/assets/state/api.js

@@ -222,10 +222,9 @@ function createTimeoutError(method, path, timeoutMs) {
  * }}
  */
 export function createMutationQueue(model, rerender) {
-  /** @type {Array<{ optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
+  /** @type {Array<{ mutationId: string, optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
   const queue = [];
   let processing = false;
-  let nextMutationId = 1;
   /** @type {Array<() => void>} */
   let flushResolvers = [];
 
@@ -246,7 +245,7 @@ export function createMutationQueue(model, rerender) {
 
     while (queue.length > 0) {
       const mutation = queue.shift();
-      if (model.store.notice?.retryMutationId !== mutation.id) {
+      if (model.store.notice?.retryMutationId !== mutation.mutationId) {
         model.store.notice = null;
       }
 
@@ -258,8 +257,8 @@ export function createMutationQueue(model, rerender) {
 
       try {
         if (typeof mutation.optimistic === "function") {
-          const previousSnapshot = cloneSnapshot(model.store.snapshot);
-          const optimisticSnapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
+          const previousSnapshot = model.store.snapshot;
+          const optimisticSnapshot = mutation.optimistic(cloneSnapshot(previousSnapshot));
           inverseDelta = computeInverseDelta(previousSnapshot, optimisticSnapshot);
           model.store.snapshot = optimisticSnapshot;
           // Direct snapshot mutation bypasses setState/syncState; invalidate
@@ -298,7 +297,7 @@ export function createMutationQueue(model, rerender) {
           title: "Action failed",
           message,
           retryLabel: "Retry",
-          retryMutationId: mutation.id,
+          retryMutationId: mutation.mutationId,
         };
 
         if (typeof mutation.onError === "function") {
@@ -318,8 +317,10 @@ export function createMutationQueue(model, rerender) {
 
   return {
     enqueue(mutation) {
-      queue.push({ ...mutation, id: nextMutationId });
-      nextMutationId += 1;
+      queue.push({
+        ...mutation,
+        mutationId: mutation.mutationId ?? crypto.randomUUID(),
+      });
       processNext();
     },
 
@@ -569,7 +570,7 @@ export function createApi(model, options) {
  *
  * @param {object} model - Store with `applySnapshotDelta` method
  * @param {object} options
- * @param {string} options.sessionToken - Auth token (forwarded as ?token=)
+ * @param {string} options.sessionToken - Auth token for API parity; EventSource uses the same-origin HttpOnly cookie.
  * @param {function} options.rerender - Trigger UI rerender after applying deltas
  * @param {typeof EventSource} [options.EventSourceCtor] - Constructor override for tests
  * @param {string} [options.path] - Override stream path; default /api/snapshot/stream
@@ -577,7 +578,6 @@ export function createApi(model, options) {
  */
 export function subscribeSnapshotStream(model, options) {
   const {
-    sessionToken,
     rerender,
     EventSourceCtor = typeof EventSource !== "undefined" ? EventSource : null,
     path = "/api/snapshot/stream",
@@ -587,14 +587,20 @@ export function subscribeSnapshotStream(model, options) {
     return { dispose: () => {}, eventSource: null };
   }
 
-  // EventSource cannot set custom headers, so the auth token rides as a query
-  // parameter. Server `extractToken` already accepts ?token=.
-  const url = sessionToken && sessionToken.length > 0
-    ? `${path}?token=${encodeURIComponent(sessionToken)}`
-    : path;
-
   let disposed = false;
-  const eventSource = new EventSourceCtor(url);
+  let consecutiveErrors = 0;
+  const eventSource = new EventSourceCtor(path);
+
+  const clearLiveUpdateNotice = () => {
+    if (model.store?.notice?.code === "live_updates_disconnected") {
+      model.store.notice = null;
+    }
+  };
+
+  const markLiveUpdateSuccess = () => {
+    consecutiveErrors = 0;
+    clearLiveUpdateNotice();
+  };
 
   const handleSnapshotDelta = (event) => {
     if (disposed) return;
@@ -613,6 +619,7 @@ export function subscribeSnapshotStream(model, options) {
     const delta = payload?.snapshotDelta;
     if (!delta || typeof delta !== "object") return;
     model.applySnapshotDelta(delta);
+    markLiveUpdateSuccess();
     if (typeof rerender === "function") rerender();
   };
 
@@ -632,27 +639,42 @@ export function subscribeSnapshotStream(model, options) {
     if (!snapshot || typeof snapshot !== "object") return;
     if (typeof model.replaceSnapshot === "function") {
       model.replaceSnapshot(snapshot);
+      markLiveUpdateSuccess();
       if (typeof rerender === "function") rerender();
     }
   };
 
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    try {
+      eventSource.close();
+    } catch {
+      // best-effort
+    }
+  }
+
   const handleError = () => {
     if (disposed) return;
-    // Surface the disconnect to the user so they don't silently miss live
-    // updates. EventSource will keep auto-reconnecting; once a snapshot/
-    // snapshotDelta event lands again, the regular notice clearing flow
-    // (e.g. on the next mutation) replaces this notice.
+    consecutiveErrors += 1;
     if (model.store && typeof model.store === "object") {
       const existing = model.store.notice;
-      if (!existing || existing.code !== "live_updates_disconnected") {
+      const disabled = consecutiveErrors >= 5;
+      const nextCode = disabled ? "live_updates_disabled" : "live_updates_disconnected";
+      if (!existing || existing.code !== nextCode) {
         model.store.notice = {
           type: "warning",
-          code: "live_updates_disconnected",
-          title: "Live updates disconnected",
-          message: "Reconnecting to the server. Changes from other sessions may be delayed.",
+          code: nextCode,
+          title: disabled ? "Live updates disabled" : "Live updates disconnected",
+          message: disabled
+            ? "Refresh the board to resume live updates from other sessions."
+            : "Reconnecting to the server. Changes from other sessions may be delayed.",
         };
         if (typeof rerender === "function") rerender();
       }
+      if (disabled) {
+        dispose();
+      }
     }
   };
 
@@ -665,14 +687,6 @@ export function subscribeSnapshotStream(model, options) {
 
   return {
     eventSource,
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      try {
-        eventSource.close();
-      } catch {
-        // best-effort
-      }
-    },
+    dispose,
   };
 }