trekoon 0.4.0 → 0.4.2

package/docs/ai-agents.md

@@ -89,6 +89,10 @@ Typical flow:
 4. Execute the plan (reads `reference/execution.md` internally)
 5. Update progress, blockers, and completion state as you go
 
+> **Experimental — not for routine agent use:** `trekoon serve` and the
+> `--daemon` flag are experimental. Use the default one-shot CLI path for
+> any production or automated agent workflow until daemon mode stabilizes.
+
 ## Default execution loop
 
 The core loop: **session, work, task done, repeat**.
@@ -113,14 +117,24 @@ If the session shows you're behind, pull tracker events before claiming work:
 trekoon --toon sync pull --from main
 ```
 
-Claim work, assign ownership, then finish or report a block:
+Claim work atomically using SQL compare-and-swap (recommended for parallel
+agents), then finish or report a block:
 
 ```bash
-trekoon --toon task update <task-id> --status in_progress --owner "agent-1"
+trekoon --toon task claim <task-id> --owner "agent-1"
 trekoon --toon task done <task-id>
 trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
 ```
 
+`task claim` is the safe primitive for parallel agents. Two concurrent calls on
+the same task return exactly one `claimed: true`. Check `data.claimed` before
+proceeding — if false, another agent won the race.
+
+```bash
+# Fallback: non-atomic claim (single-agent or sequential workflows only)
+trekoon --toon task update <task-id> --status in_progress --owner "agent-1"
+```
+
 Use `task done` when the task is actually finished. It marks the task complete,
 auto-transitions through `in_progress` if needed, reports newly unblocked
 downstream tasks, warns about incomplete subtasks, and returns the next ready
@@ -201,6 +215,7 @@ Use the narrowest command that answers the question:
 | One task with subtasks | `trekoon --toon task show <task-id> --all` |
 | One epic tree | `trekoon --toon epic show <epic-id> --all` |
 | Export epic to Markdown | `trekoon --toon epic export <epic-id>` |
+| Snapshot the DB before manual recovery | `trekoon --toon migrate backup [--retain <n>]` |
 | Repeated text in one scope | `trekoon --toon epic|task|subtask search ...` |
 
 For repeated text changes, use the safe replace loop:

package/docs/commands.md

@@ -12,11 +12,11 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 - `trekoon epic <create|expand|list|show|search|replace|update|delete|progress>`
 - `trekoon session [--epic <epic-id>]`
 - `trekoon suggest [--epic <epic-id>]`
-- `trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete>`
-- `trekoon subtask <create|create-many|list|search|replace|update|delete>`
+- `trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete|claim>`
+- `trekoon subtask <create|create-many|list|search|replace|update|delete|claim>`
 - `trekoon dep <add|add-many|remove|list|reverse>`
 - `trekoon events prune [--dry-run] [--archive] [--retention-days <n>]`
-- `trekoon migrate <status|rollback> [--to-version <n>]`
+- `trekoon migrate <status|rollback|backup> [--to-version <n>] [--retain <n>]`
 - `trekoon sync status [--from <branch>]`
 - `trekoon sync pull --from <branch>`
 - `trekoon sync resolve <conflict-id> --use ours|theirs [--dry-run]`
@@ -26,6 +26,7 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 - `trekoon skills install -g|--global [--editor opencode|claude|pi]`
 - `trekoon skills update`
 - `trekoon wipe --yes`
+- `trekoon serve` (experimental)
 
 ## Global options
 
@@ -33,6 +34,7 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 - `--toon` — TOON-encoded output (preferred for agent loops)
 - `--compact` — strips contract metadata from TOON/JSON envelopes
 - `--compat <mode>` — explicit machine compatibility behavior
+- `--daemon` — (experimental) route the call through a running `trekoon serve` daemon over a Unix socket; transparently falls back to the in-process CLI when no daemon is reachable. Equivalent to `TREKOON_DAEMON=1`.
 - `--help` — root and command help
 - `--version` — CLI version
 
@@ -73,6 +75,7 @@ Board API endpoints (all require token authentication):
 | Method | Endpoint | Purpose |
 | --- | --- | --- |
 | `GET` | `/api/snapshot` | Full board state (epics, tasks, subtasks, deps, counts) |
+| `GET` | `/api/snapshot/stream` | Server-sent events stream of `snapshot` and `snapshotDelta` events for live updates |
 | `PATCH` | `/api/epics/{id}` | Update epic title, description, or status |
 | `PATCH` | `/api/tasks/{id}` | Update task title, description, status, or owner |
 | `PATCH` | `/api/subtasks/{id}` | Update subtask title, description, status, or owner |
@@ -81,6 +84,19 @@ Board API endpoints (all require token authentication):
 | `POST` | `/api/dependencies` | Add dependency edge (sourceId, dependsOnId) |
 | `DELETE` | `/api/dependencies?sourceId=...&dependsOnId=...` | Remove dependency |
 
+**Note:** the SSE auth token rides as a `?token=` query parameter on
+`/api/snapshot/stream` (EventSource cannot set custom headers), so it may
+appear in reverse-proxy access logs; treat access logs as sensitive if the
+board is exposed beyond localhost.
+
+Board mutations from any source — board UI, CLI in another shell, or another
+worktree — propagate to every connected client through the SSE stream. The CLI
+side is driven by a WAL-watcher that diffs the snapshot when
+`.trekoon/trekoon.db-wal` changes; in-process mutations publish deltas
+directly. PATCH endpoints accept `If-Match: <updatedAt-ms>` for optimistic
+concurrency: a stale value returns `409` with `currentUpdatedAt`. Missing
+`If-Match` is allowed for back-compat.
+
 Board commands don't accept command-specific options yet. For tests and local
 development, `TREKOON_BOARD_ASSET_ROOT` overrides the bundled asset source.
 
@@ -183,6 +199,41 @@ trekoon subtask update <subtask-id> --owner "agent-2"
 
 Also accepted on `PATCH /api/tasks/{id}` and `PATCH /api/subtasks/{id}`.
 
+## Task claim
+
+```bash
+trekoon task claim <task-id> --owner <owner>
+trekoon subtask claim <subtask-id> --owner <owner>
+```
+
+Atomically claim a task (or subtask) using a SQL compare-and-swap. Sets
+`status=in_progress` and `owner=<owner>` only when:
+
+- The task is in `todo` or `blocked` status, **and**
+- The `owner` column is `NULL` or already equal to `<owner>` (re-entrant claim)
+
+Two concurrent `task claim` calls racing on the same task return exactly one
+`claimed: true`. The loser gets `claimed: false` with `currentOwner` and
+`currentStatus` reflecting the winner's write.
+
+`--owner` is required.
+
+Response envelope:
+
+```text
+ok: true
+command: task.claim | subtask.claim
+data:
+  claimed: true | false
+  currentOwner: <owner> | null
+  currentStatus: in_progress | todo | blocked | done
+  task | subtask: { ...full record... }   # present only when claimed=true
+```
+
+When `claimed` is false, `task`/`subtask` is absent. `currentOwner` tells you
+who holds the lock. `currentStatus` tells you why the claim failed (already
+`done`, or `in_progress` by another owner).
+
 ## Task done
 
 `trekoon task done <task-id>` marks a task complete and returns the next ready
@@ -289,6 +340,99 @@ trekoon --toon sync conflicts show <conflict-id>
 `list` defaults to `--mode pending`. Use `--mode all` to include resolved
 conflicts.
 
+## Migrate commands
+
+### `migrate status`
+
+```bash
+trekoon --toon migrate status
+```
+
+Reports `currentVersion`, `latestVersion`, and pending migration count.
+
+### `migrate rollback`
+
+```bash
+trekoon --toon migrate rollback [--to-version <n>]
+```
+
+Rolls back schema migrations one version (default) or down to `--to-version`.
+Migrations 0004, 0005, and 0006 are irreversible (ALTER TABLE plus dependency
+data cleanup). Rolling back below those versions errors with code
+`migration_down_unsupported`. Take a backup first; restore by copying the
+backup over `.trekoon/trekoon.db`.
+
+### `migrate backup`
+
+```bash
+trekoon --toon migrate backup
+trekoon --toon migrate backup --retain 5
+```
+
+Snapshots `.trekoon/trekoon.db` to a timestamped sibling file
+(`trekoon.db.backup-<ISO8601>`) using SQLite `VACUUM INTO`. The source database
+is opened read-only, so a backup never mutates live state. Returns
+`backupPath`, `bytes`, `migrationVersion`, and `latestVersion` for machine
+consumers. Backups stay inside `.trekoon/` and are gitignored along with the
+rest of the directory.
+
+`--retain <n>` keeps the last `n` timestamped backups; older siblings are
+pruned in the same call. Default is `10`. Backups created within the same
+millisecond produce a deterministic collision error that names the existing
+file so operators can identify it.
+
+To restore from a backup: stop any process holding the DB, then copy the
+backup file over `.trekoon/trekoon.db`.
+
+## Daemon (experimental)
+
+`trekoon serve` runs Trekoon as a long-lived process listening
+on a Unix-domain socket inside `<storage-root>/.trekoon/daemon.sock`. The
+daemon holds the SQLite connection in memory, so subsequent invocations skip
+Bun startup, module load, migration probes, and database open.
+
+Status: **experimental**. Not on by default. The default one-shot CLI behavior
+is unchanged whether or not the daemon is running.
+
+Activate the client with one of:
+
+```bash
+TREKOON_DAEMON=1 trekoon session
+trekoon --daemon session
+```
+
+If no daemon is reachable, the client transparently falls back to the in-process
+one-shot path. Calls run against the daemon return envelopes equivalent to the
+in-process call modulo:
+
+- The per-request `requestId` and `persistedAt` fields.
+- Environment variables. The client's `process.env` is **not** forwarded over
+  the socket; the daemon process uses the environment captured at `trekoon
+  serve` startup. If a command's behavior depends on an env var (e.g. an
+  override flag), set it before launching the daemon — not on the client side.
+
+The daemon request contract is `{argv, cwd}` only — there is no per-call env
+channel. This narrows the secret-leak surface area and keeps the equivalence
+claim crisp.
+
+Security:
+
+- Socket file mode `0o600`; parent `.trekoon/` directory forced to `0o700`.
+- The umask is tightened to `0o077` around `server.listen()` so the socket
+  inode is created with restrictive perms (no TOCTOU window before chmod).
+- Daemon error envelopes return a sanitized message only — no stack trace,
+  which would otherwise leak filesystem paths or secret-bearing error text.
+  Stacks are still routed to the daemon's local `console.error` for operator
+  debugging.
+- Client env is not transmitted over the socket (see equivalence note above).
+- Stale sockets from prior crashes are unlinked at startup.
+- On `Ctrl-C` / `SIGTERM` the socket is unlinked and the cached database
+  connection is closed.
+
+Performance (see `bench/daemon-session.ts`): daemon median < 10 ms,
+cold one-shot median > 50 ms — roughly a 5–10× latency reduction for
+repeated calls by reusing the held-open SQLite connection.
+
 ## Related docs
 
 - [Quickstart](quickstart.md)

package/docs/machine-contracts.md

@@ -254,6 +254,12 @@ data:
 Transition details are in `data`, not `error.details`. `error` only has `code`
 and `message`.
 
+**Allowed bypass:** `task done` performs an atomic single-transaction direct
+write to `done` from any non-`done` status (`todo`, `blocked`, `in_progress`),
+emitting one `task.updated` event — there is no intermediate `in_progress`
+event when starting from `todo`/`blocked`. This is the only sanctioned
+bypass of the status-machine checker.
+
 ## Epic progress
 
 ```bash
@@ -328,6 +334,69 @@ data:
     pendingConflicts
 ```
 
+## Task claim
+
+```bash
+trekoon --toon task claim <task-id> --owner <owner>
+trekoon --toon subtask claim <subtask-id> --owner <owner>
+```
+
+Atomically claims a task or subtask using SQL compare-and-swap. The single
+UPDATE predicate ensures exactly one concurrent caller gets `claimed: true`.
+
+Success (claimed):
+
+```text
+ok: true
+command: task.claim | subtask.claim
+data:
+  claimed: true
+  currentOwner: <owner>
+  currentStatus: in_progress
+  task | subtask: { ...full record... }
+```
+
+Not claimed (another owner holds it, or status is done/in_progress by others):
+
+```text
+ok: true
+command: task.claim | subtask.claim
+data:
+  claimed: false
+  currentOwner: <string> | null
+  currentStatus: in_progress | done | todo | blocked
+```
+
+Note: `claimed: false` is a successful response (`ok: true`). The command
+reports the current state, not an error condition. Check `data.claimed` to
+distinguish the two cases.
+
+Dependency gating on claim (cr-expert hardening): when the task or subtask is
+in `blocked` or `todo` and has unresolved dependencies, the claim atomically
+fails with `code: dependency_blocked` rather than flipping the row into
+`in_progress`. This mirrors `task done` semantics so neither
+forward-progress transition (`todo|blocked → in_progress` via claim,
+`* → done` via `task done`) can bypass dependency resolution.
+
+```text
+ok: false
+command: task.claim | subtask.claim
+error:
+  code: dependency_blocked
+  message: "task cannot transition to in_progress while dependencies are unresolved"
+data:
+  unresolvedDependencyCount: <number>
+  unresolvedDependencyIds: [<id>, ...]
+  unresolvedDependencies: [{ id, kind, status }, ...]
+```
+
+The only intentional direct-status-write exception in the codebase remains
+`MutationService.markTaskDoneAtomically`, which bypasses
+`validateStatusTransition` for the `* → done` flip but still goes through
+`assertNoUnresolvedDependenciesForStatusTransition` before issuing the UPDATE.
+No other call site is permitted to write `status` directly without going
+through the public transition checker.
+
 ## Owner field in updates
 
 Task and subtask update payloads include `owner`:
@@ -538,6 +607,60 @@ error:
   message: "Pending conflicts changed before batch resolution could be applied."
 ```
 
+## Error code registry
+
+All machine-visible error codes emitted by Trekoon. Every `error.code` value in
+any `ok: false` response will be one of the following strings.
+
+| Code | Description |
+|---|---|
+| `already_done` | Entity is already in `done` status; transition is a no-op. |
+| `already_resolved` | Conflict was resolved by another process before this write. |
+| `ambiguous_legacy_state` | Legacy worktree state is ambiguous and cannot be automatically resolved. |
+| `backpressure` | SSE snapshot stream disconnected a slow client whose queued bytes exceeded the hard limit. |
+| `backup_already_exists` | A backup file already exists at the target path; overwrite was not requested. |
+| `backup_database_missing` | Source database file not found when attempting to create a backup. |
+| `backup_failed` | Backup operation failed (I/O or copy error). |
+| `cancelled` | Operation was cancelled by the user (e.g. confirmation prompt rejected). |
+| `confirmation_required` | Human-mode operation requires explicit confirmation before proceeding. |
+| `conflict_set_changed` | Batch conflict set changed between preview and confirmed write. |
+| `daemon_start_failed` | Daemon failed to start (socket bind error or already running). |
+| `database_busy` | SQLite database is locked; retry after a short wait. |
+| `dependency_blocked` | Cascade update blocked because one or more descendants have unresolved dependencies. |
+| `disallowed_field` | Sync resolve attempted to write a field that is not on the allow-list. |
+| `events_failed` | Event log query or export failed. |
+| `install_failed` | Skill installation failed (file copy or permission error). |
+| `internal_error` | Unexpected internal error; inspect server logs for details. |
+| `invalid_args` | Required positional arguments are missing or malformed. |
+| `invalid_dependency` | Dependency edge is invalid (self-loop, wrong entity type, or duplicate). |
+| `invalid_input` | One or more option values failed validation. |
+| `invalid_path` | File path is invalid for the requested operation (e.g. path is a directory). |
+| `invalid_source` | Source entity for a dependency or sync operation does not exist or is of wrong kind. |
+| `invalid_state` | Entity or system is in a state that does not permit the requested operation. |
+| `invalid_subcommand` | Unrecognised subcommand for this command group. |
+| `legacy_import_failed` | Import from a legacy (pre-`.trekoon`) data directory failed. |
+| `migrate_failed` | Database schema migration failed. |
+| `migration_down_unsupported` | Down-migrations are not supported; only forward migrations are allowed. |
+| `missing_asset` | Expected bundled asset (skill file, template) was not found. |
+| `no_matching_conflicts` | `sync resolve --all` filters matched zero pending conflicts. |
+| `not_found` | Requested entity (epic, task, subtask, dependency) does not exist. |
+| `orphaned_external_node` | Dependency graph contains a node that belongs to a different epic. |
+| `outside_repo_target` | Skill install target path is outside the repository root. |
+| `permission_denied` | File-system permission denied for the requested path. |
+| `precondition_failed` | `If-Match` precondition header did not match the entity's current `updatedAt`. |
+| `row_not_found` | Sync resolve target row no longer exists in the database. |
+| `status_transition_invalid` | Requested status transition is not permitted by the status machine. |
+| `stream_unavailable` | SSE snapshot stream is not available (board not initialised or shutting down). |
+| `sync_failed` | Sync pull or push operation failed. |
+| `tracked_ignored_mismatch` | Worktree is tracked by Trekoon but its path is in `.gitignore`, or vice-versa. |
+| `unauthorized` | Request lacks valid authentication credentials. |
+| `unhandled_command` | Command matched a known group but no case handled the subcommand. |
+| `unknown_command` | Top-level command token is not recognised. |
+| `unknown_option` | An option flag passed to the command is not recognised. |
+| `unsupported_entity_kind` | Sync resolve encountered an entity kind that the writer does not handle. |
+| `update_failed` | Skill update failed (download, copy, or permission error). |
+| `wrong_entity_type` | Operation requires a specific entity kind but a different kind was supplied. |
+
 ## Related docs
 
 - [Quickstart](quickstart.md)

package/docs/quickstart.md

@@ -148,6 +148,58 @@ a file extension means "write this file"; no extension means "put the default-
 named file in this directory". Use `--overwrite` to resave after the plan state
 changes.
 
+## Claim work atomically
+
+When multiple agents or lanes work in parallel, use `claim` to avoid races:
+
+```bash
+trekoon task claim <task-id> --owner <owner>
+trekoon subtask claim <subtask-id> --owner <owner>
+```
+
+Both commands use a SQL compare-and-swap: the claim succeeds only when the item
+is `todo` or `blocked` and the owner is `NULL` or already set to `<owner>`.
+The response includes `claimed` (true/false), `currentOwner`, `currentStatus`,
+and the full entity record on success. Two concurrent claims return exactly one
+`claimed=true`.
+
+## Database backup and migration
+
+Before any manual migration recovery, snapshot the database:
+
+```bash
+trekoon migrate backup
+trekoon migrate backup --retain 5   # keep last 5 backups (default 10)
+```
+
+This writes a timestamped copy of `.trekoon/trekoon.db` next to the live file.
+To check the current schema version or roll back:
+
+```bash
+trekoon migrate status
+trekoon migrate rollback              # one version back
+trekoon migrate rollback --to-version 1
+```
+
+## Daemon mode (experimental)
+
+> **Not for routine agent use.** `trekoon serve` and `--daemon` are
+> experimental; use the default one-shot CLI path in automated workflows.
+
+`trekoon serve` starts a foreground daemon on a Unix-domain socket inside
+`.trekoon`. Subsequent calls skip Bun startup, module load, and database
+open — per `bench/daemon-session.ts`: daemon median < 10 ms vs. cold
+one-shot median > 50 ms:
+
+```bash
+trekoon serve                         # start the daemon (foreground)
+trekoon --daemon session              # route a call through the daemon
+TREKOON_DAEMON=1 trekoon session      # same, via environment variable
+```
+
+If the socket is missing or unreachable the client falls back silently to the
+normal one-shot path. The socket is 0o600 and `.trekoon` is forced to 0o700.
+
 ## Check progress
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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

@@ -1,9 +1,10 @@
 import { createBoardActions } from "./state/actions.js";
-import { createApi } from "./state/api.js";
+import { createApi, subscribeSnapshotStream } from "./state/api.js";
 import { applyTheme, createStore, readThemePreference } from "./state/store.js";
 import { normalizeSnapshot, normalizeStatus } from "./state/utils.js";
 import { syncUrlHash } from "./state/url.js";
 import { createDelegation } from "./runtime/delegation.js";
+import { createOverlayFocusTrap } from "./runtime/focus-trap.js";
 import { createTopBar } from "./components/TopBar.js";
 import { createWorkspace } from "./components/Workspace.js";
 import { createTaskModal } from "./components/TaskModal.js";
@@ -132,15 +133,16 @@ export async function bootLegacyBoard(options = {}) {
     const runtimeSession = resolveRuntimeSession();
     if (runtimeSession.shouldScrubAddressBar) scrubTokenFromAddressBar();
 
-    // Fetch snapshot
-    const bootstrap = readJsonScript("trekoon-board-bootstrap") ?? {};
-    let snapshotPayload = bootstrap?.snapshot ?? readJsonScript("trekoon-board-snapshot") ?? {};
-    if ((!snapshotPayload || typeof snapshotPayload !== "object") && runtimeSession.token.length > 0) {
-      const response = await fetch("/api/snapshot");
-      const payload = await response.json();
-      if (!payload?.ok) throw new Error(payload?.error?.message || "Board request failed");
-      snapshotPayload = payload?.data?.snapshot ?? {};
+    // Always fetch snapshot client-side. The bootstrap script in index.html
+    // only carries the auth token; the snapshot is fetched via /api/snapshot
+    // so index.html stays small and never carries board data in its HTML body.
+    const response = await fetch("/api/snapshot");
+    if (!response.ok) {
+      throw new Error(`Board snapshot request failed with status ${response.status}`);
     }
+    const payload = await response.json();
+    if (!payload?.ok) throw new Error(payload?.error?.message || "Board request failed");
+    const snapshotPayload = payload?.data?.snapshot ?? {};
 
     const snapshot = normalizeSnapshot(snapshotPayload);
 
@@ -258,6 +260,12 @@ export async function bootLegacyBoard(options = {}) {
       overlay.focus({ preventScroll: true });
     }
 
+    const overlayFocusTrap = createOverlayFocusTrap({
+      doc: document,
+      onTabKey: (event) => trapOverlayFocus(event),
+      onFocusIn: (event) => containOverlayFocus(event),
+    });
+
     function syncOverlayEnvironment() {
       const hadOverlay = activeOverlay instanceof HTMLElement;
       const nextOverlay = getActiveOverlayElement();
@@ -271,6 +279,10 @@ export async function bootLegacyBoard(options = {}) {
           lockBackgroundScroll();
           setBackgroundInert(true);
         }
+        // Attach the document-level focus trap only while an overlay is actually
+        // open. This avoids the microtask window where Tab keydowns get swallowed
+        // by a stale handler with no overlay to confine to.
+        overlayFocusTrap.attach();
         queueMicrotask(() => focusOverlay(nextOverlay));
         return;
       }
@@ -280,6 +292,7 @@ export async function bootLegacyBoard(options = {}) {
         unlockBackgroundScroll();
         setBackgroundInert(false);
       }
+      overlayFocusTrap.detach();
       queueMicrotask(() => restoreOverlayFocus());
     }
 
@@ -355,8 +368,9 @@ export async function bootLegacyBoard(options = {}) {
       return true;
     }
 
-    document.addEventListener("keydown", trapOverlayFocus, true);
-    document.addEventListener("focusin", containOverlayFocus, true);
+    // Focus-trap listeners are attached lazily by syncOverlayEnvironment when an
+    // overlay actually opens (and detached when it closes), so plain Tab outside
+    // any overlay reaches normal browser flow.
 
     // Render cycle
     function rerender() {
@@ -365,7 +379,9 @@ export async function bootLegacyBoard(options = {}) {
       const screen = boardState.screen;
       const selectedTask = boardState.selectedTask;
       const selectedSubtask = boardState.selectedSubtask;
-      const currentNav = selectedTask ? "detail" : screen === "tasks" ? "board" : "epics";
+      const taskModalOpen = Boolean(boardState.taskModalOpen && selectedTask);
+      const subtaskModalOpen = Boolean(boardState.subtaskModalOpen && selectedSubtask);
+      const currentNav = taskModalOpen ? "detail" : screen === "tasks" ? "board" : "epics";
 
       // Layout toggles
       const showTasks = screen === "tasks" && boardState.selectedEpic;
@@ -381,11 +397,11 @@ export async function bootLegacyBoard(options = {}) {
         confirmDialog.update(null);
       }
 
-      if (!showTasks || !selectedTask) {
+      if (!showTasks || !taskModalOpen) {
         taskModal.update(null);
       }
 
-      if (!showTasks || !selectedTask || !selectedSubtask) {
+      if (!showTasks || !taskModalOpen || !subtaskModalOpen) {
         subtaskModal.update(null);
       }
 
@@ -428,7 +444,7 @@ export async function bootLegacyBoard(options = {}) {
           visibleTasks: boardState.visibleTasks,
         });
 
-        taskModal.update(selectedTask ? {
+        taskModal.update(taskModalOpen ? {
           task: selectedTask,
           epics: store.snapshot.epics,
           snapshot: store.snapshot,
@@ -442,7 +458,7 @@ export async function bootLegacyBoard(options = {}) {
         });
       }
 
-      subtaskModal.update(showTasks && selectedTask && selectedSubtask ? {
+      subtaskModal.update(showTasks && taskModalOpen && subtaskModalOpen ? {
         subtask: selectedSubtask,
         isMutating: store.isMutating,
       } : null);
@@ -452,6 +468,22 @@ export async function bootLegacyBoard(options = {}) {
 
     const api = createApi(model, { sessionToken: runtimeSession.token, rerender });
 
+    // Subscribe to /api/snapshot/stream so external CLI writes (picked up by
+    // the WAL watcher) and concurrent-tab mutations are reflected in this
+    // board within ~1s without manual refresh. applySnapshotDelta is idempotent
+    // so re-receiving deltas already applied via mutation responses is safe.
+    // Capture the handle so we can tear it down on page unload (and so tests
+    // and future teardown paths can dispose the EventSource).
+    const snapshotSubscription = subscribeSnapshotStream(model, {
+      sessionToken: runtimeSession.token,
+      rerender,
+    });
+    if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+      window.addEventListener("beforeunload", () => {
+        snapshotSubscription.dispose();
+      }, { once: true });
+    }
+
     // Actions for delegation
     const actions = createBoardActions({
       model,
@@ -550,6 +582,7 @@ export async function bootLegacyBoard(options = {}) {
       addDependency: (src, data) => actions.addDependency(src, data),
       dropTaskStatus: (id, status) => actions.dropTaskStatus(id, status),
       getTaskStatus: (id) => actions.getTaskStatus(id),
+      setDragFeedback: (feedback) => actions.setDragFeedback(feedback),
       changeEpicStatus: (epicId, status) => actions.changeEpicStatus(epicId, status),
       bulkSetStatus: (epicId, status) => actions.bulkSetStatus(epicId, status),
       toggleEpicStatusFilter: (status) => actions.toggleEpicStatusFilter(status),