trekoon 0.4.3 → 0.4.5

package/.agents/skills/trekoon/SKILL.md

@@ -98,6 +98,10 @@ matches the user intent.
   `task next`, `dep list`, `dep reverse`, targeted `show`.
 - Prefer transactional/bulk commands for planning and narrow `--ids` for bulk
   updates.
+- In Claude Code, keep parallel `Bash` batches read-only for Trekoon commands.
+  Only `task claim` and `subtask claim` are safe parallel write exceptions.
+  Run `task done` and other status-changing commands sequentially after reading
+  current state.
 - Append progress, verification, and blocker notes with `--append`; do not
   rewrite descriptions unless fixing the plan itself.
 - Preview search/replace before `--apply`.
@@ -112,7 +116,8 @@ matches the user intent.
 Normal status flow is `todo -> in_progress -> done`; `blocked` requires an
 appended reason. Use `task done` for task completion because it auto-transitions
 from `todo` or `blocked` through `in_progress`. Load
-`reference/status-machine.md` for transition errors or uncertainty.
+`reference/status-machine.md` for transition errors or uncertainty. For
+subtasks, claim or move through `in_progress` before marking `done`.
 
 ## Recovery
 

package/.agents/skills/trekoon/reference/execution-with-team.md

@@ -47,7 +47,10 @@ TaskCreate:
     While working:
     - Complete required subtasks.
     - Append progress notes; do not rewrite task descriptions.
-    - Use task done for completion.
+    - Use task done for task completion.
+    - For subtasks, claim or move through in_progress before done.
+    - Keep parallel Trekoon Bash calls read-only; serialize status-changing
+      commands unless using atomic claim.
     - Use --compact for noisy Trekoon reads.
 
     On completion:
@@ -82,7 +85,9 @@ Agent:
     Claim each Trekoon task before editing:
       trekoon --toon task claim <trekoon-task-id> --owner <your-name>
 
-    Use task done for completion. Read and report unblocked tasks, warnings,
+    Use task done for task completion. For subtasks, claim or move through
+    in_progress before done. Do not batch multiple Trekoon status-changing Bash
+    calls in one parallel tool turn. Read and report unblocked tasks, warnings,
     and next candidate via SendMessage.
 
     Communicate blockers and coordination needs via SendMessage.
@@ -126,6 +131,10 @@ For `status_transition_invalid`, inspect current status with:
 trekoon --toon --compact task show <id>
 ```
 
+If the error came from a cancelled parallel Bash batch, first re-read the
+affected task or subtask, then retry only the valid next transition. Do not
+replay the whole batch.
+
 For `dependency_blocked`, inspect the dependency, append a blocker note, then
 continue with a ready candidate from:
 

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

@@ -86,7 +86,8 @@ Before each task:
 While working:
 - Complete required subtasks and update subtask statuses.
 - Append meaningful progress notes; do not rewrite task descriptions.
-- Respect status flow: todo -> in_progress -> done. Use task done for completion.
+- Respect status flow: todo -> in_progress -> done. Use task done for task
+  completion; for subtasks, claim or move through in_progress before done.
 - Assume other agents may edit unrelated files. Do not revert unrelated changes.
 
 On completion:
@@ -102,6 +103,16 @@ If blocked:
 Use --compact in noisy Trekoon reads. Do not create branches, commits, pushes,
 or PRs unless the user explicitly asked and harness policy allows it.
 
+Claude Code parallel tool calls:
+- Parallel Trekoon Bash calls are for read-only commands such as session,
+  progress, ready, suggest, and targeted show.
+- Do not issue multiple Trekoon status-changing Bash commands in one parallel
+  tool batch. Use task/subtask claim for atomic races, then serialize updates
+  and completion commands.
+- If a parallel batch reports sibling cancellation, re-read the affected task or
+  subtask before retrying; recover from current Trekoon state, not the cancelled
+  command text.
+
 Final report: tasks completed, files changed, checks, review result/gap,
 task done response, blockers.
 ```

package/.agents/skills/trekoon/reference/harness-primitives.md

@@ -46,7 +46,10 @@ coordinating from the parent session?
   `wait_agent`, `resume_agent`, and `close_agent`.
 - Claude Code: use normal subagents for bounded side work. Use Agent Teams only
   when the user explicitly asks for team execution and the environment supports
-  it.
+  it. Treat parallel `Bash` tool calls as read-only unless every command is a
+  safe atomic claim. Do not batch multiple Trekoon status-changing commands in
+  one parallel tool turn; run them sequentially so one failed transition does
+  not cancel sibling mutations.
 - OpenCode: use `@explore` for read-only discovery and `@general` or native
   Task for write-capable lane work. Use `question` when available.
 - Pi/other harnesses: use the same intent and native task/subagent/question

package/README.md

@@ -196,14 +196,19 @@ call it from any non-done status.
 
 ## Local board
 
-Trekoon includes a browser-based board for humans who like having visual overview.
-No build step, no framework dependencies, works offline.
+Trekoon includes a browser-based board for humans who like having a visual
+overview. No build step, no framework dependencies, works offline.
 
 ```bash
 trekoon board open      # starts a local server, opens browser
-trekoon board update    # refresh assets only
 ```
 
+Board code (HTML, JS, CSS, fonts) comes from the running Trekoon install.
+Board data comes from the repo where `trekoon board open` is invoked. Updating
+Trekoon updates the board bundle; no per-repo asset copy is needed.
+Repos with an old ignored `.trekoon/board` directory keep those files on disk,
+but Trekoon no longer reads or refreshes them.
+
 Binds to `127.0.0.1` only with a per-session token. Gives you an epics
 overview, kanban workspace per epic, task detail modals, and search. The board
 client subscribes to `/api/snapshot/stream` (SSE), so mutations from another

package/docs/ai-agents.md

@@ -274,6 +274,14 @@ trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "pa
 trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply
 ```
 
+For Claude Code and similar harnesses with parallel tool calls, keep parallel
+Trekoon `Bash` batches read-only. It is safe to fan out `session`, `progress`,
+`ready`, `suggest`, and targeted `show` commands. Do not batch multiple
+status-changing Trekoon commands in one parallel tool turn; if one transition
+fails, sibling calls may be cancelled and the agent must re-read state before
+retrying. Use `task claim` / `subtask claim` for atomic races, then serialize
+status updates and completion commands.
+
 ## Shared-database model
 
 Trekoon uses one live SQLite database per repository at

package/docs/commands.md

@@ -6,7 +6,7 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 ## Command surface
 
 - `trekoon init`
-- `trekoon board <open|update>`
+- `trekoon board <open>`
 - `trekoon help [command]`
 - `trekoon quickstart`
 - `trekoon epic <create|expand|list|show|search|replace|update|delete|progress>`
@@ -50,25 +50,31 @@ also accept `-h` and `-v`.
 
 ## Board commands
 
-`trekoon board open` installs board assets (if needed), starts a loopback-only
-server on `127.0.0.1` with a random port, opens the browser, and returns the
-board URL plus a manual fallback URL.
+`trekoon board open` starts a loopback-only server on `127.0.0.1` with a
+random port, opens the browser, and returns the board URL plus a manual
+fallback URL.
 
-`trekoon board update` refreshes board runtime assets without starting the
-server or opening a browser. Use this when you need to update copied assets
-before the next launch.
+Board code (HTML, JS, CSS, fonts) comes from the running Trekoon install —
+a global install serves the global package assets; a project-local install
+serves the project-local package assets. Board data comes from the repo where
+`trekoon board open` is invoked. Updating Trekoon updates the board bundle;
+no per-repo asset copy is needed.
 
 Security model:
 
 - Every `board open` session gets a unique token
-- Requests must include it as `Authorization: Bearer {token}`,
-  `x-trekoon-token` header, or `?token={token}` query parameter
+- Initial board HTML bootstrap accepts `?token={token}` once, sets an
+  HttpOnly `trekoon_board_session` cookie, and redirects to the same URL
+  without the token query parameter
+- Board API requests must authenticate with the session cookie,
+  `Authorization: Bearer {token}`, or `x-trekoon-token` header
+- API routes reject token query parameters
+- `/api/snapshot/stream` is authenticated by the session cookie
 - Invalid tokens return `401`
 - Static responses use `cache-control: no-store`
 
 The board is a self-hosted single-page app (vanilla JS, bundled CSS and fonts,
-no framework or CDN dependencies) served from `.trekoon/board`. Works fully
-offline once initialized.
+no framework or CDN dependencies). Works fully offline.
 
 Board API endpoints (all require token authentication):
 
@@ -84,27 +90,30 @@ 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.
+directly. PATCH endpoints accept `If-Match: <version>` for optimistic
+concurrency; RFC 7232 strong or `W/`-prefixed weak ETag forms are accepted,
+but the `*` wildcard is not. A stale value returns `409` with
+`currentVersion` and `providedVersion`. Missing `If-Match` is allowed for
+back-compat.
+
+Repos that already have an ignored `.trekoon/board` directory keep those files
+on disk, but current Trekoon versions no longer read, create, refresh, or
+delete them. Remove that directory manually only if you want to clean up the
+old copied board bundle.
+
+`trekoon board open` accepts `--reveal-token` to include the raw tokenized URL,
+server token, and browser launch arguments in machine output. Other board
+subcommands and flags are rejected. `TREKOON_BOARD_ASSET_ROOT` overrides the
+asset source for tests and local development.
 
 ```bash
 trekoon init
 trekoon board open
 trekoon --json board open
-trekoon board update
 ```
 
 ## Human views

package/docs/machine-contracts.md

@@ -647,7 +647,7 @@ any `ok: false` response will be one of the following strings.
 | `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`. |
+| `precondition_failed` | `If-Match` precondition header did not match the entity's current version. Error details include `currentVersion` and `providedVersion`. |
 | `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). |

package/docs/quickstart.md

@@ -50,9 +50,8 @@ trekoon --toon init
 trekoon --toon sync status
 ```
 
-Run `init` once per repository. It creates the shared storage root and installs
-the board runtime under `.trekoon/board`. If `sync status` reports
-`recoveryRequired` or a tracked/ignored mismatch, fix the setup before
+Run `init` once per repository. It creates the shared storage root. If `sync status`
+reports `recoveryRequired` or a tracked/ignored mismatch, fix the setup before
 continuing.
 
 ## Open the board
@@ -62,9 +61,10 @@ trekoon board open
 ```
 
 Starts a loopback-only server on `127.0.0.1`, opens the browser, and prints a
-fallback URL. The board is a self-hosted single-page app with no CDN
-dependencies, so it works offline once initialized. Use `trekoon board update`
-if you just need to refresh the runtime assets without opening the browser.
+fallback URL. Board code (HTML, JS, CSS, fonts) comes from the running Trekoon
+install; board data comes from the repo where the command is invoked. The board
+works fully offline. To get an updated board UI, update Trekoon itself. Old
+ignored `.trekoon/board` copies are left on disk but are no longer used.
 
 ## Create work
 
@@ -163,6 +163,10 @@ The response includes `claimed` (true/false), `currentOwner`, `currentStatus`,
 and the full entity record on success. Two concurrent claims return exactly one
 `claimed=true`.
 
+In Claude Code, keep parallel Trekoon `Bash` calls read-only unless the command
+is an atomic `claim`. Run status updates and completion commands sequentially so
+a failed transition does not cancel sibling mutations.
+
 ## Database backup and migration
 
 Before any manual migration recovery, snapshot the database:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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",
@@ -40,7 +40,7 @@
   ],
   "scripts": {
     "run": "bun run ./src/index.ts",
-    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && cp ./package.json ./dist/package.json && rm -rf ./dist/assets && cp -R ./src/board/assets ./dist/assets",
     "test": "bun test ./tests",
     "lint": "bunx tsc --noEmit"
   },

package/src/board/asset-root.ts

@@ -0,0 +1,73 @@
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { BoardAssetError } from "./types";
+
+export const BOARD_BUNDLED_ASSET_DIRNAME = "assets";
+export const BOARD_ENTRY_FILENAME = "index.html";
+export const BOARD_ASSET_ROOT_ENV_VAR = "TREKOON_BOARD_ASSET_ROOT";
+
+export type BoardAssetRootSource = "override" | "environment" | "package";
+
+export interface BoardAssetRoot {
+  readonly assetRoot: string;
+  readonly entryFile: string;
+  readonly source: BoardAssetRootSource;
+}
+
+export interface ResolveBoardAssetRootOptions {
+  readonly assetRootOverride?: string;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+function resolvePackageBoardAssetRoot(): string {
+  return fileURLToPath(new URL(`./${BOARD_BUNDLED_ASSET_DIRNAME}`, import.meta.url));
+}
+
+interface SelectedAssetRoot {
+  readonly rootPath: string;
+  readonly source: BoardAssetRootSource;
+}
+
+function selectAssetRoot(options: ResolveBoardAssetRootOptions): SelectedAssetRoot {
+  if (options.assetRootOverride !== undefined) {
+    return { rootPath: resolve(options.assetRootOverride), source: "override" };
+  }
+
+  const env = options.env ?? process.env;
+  const envOverrideRaw = env[BOARD_ASSET_ROOT_ENV_VAR];
+  const envOverride = typeof envOverrideRaw === "string" ? envOverrideRaw.trim() : "";
+  if (envOverride.length > 0) {
+    return { rootPath: resolve(envOverride), source: "environment" };
+  }
+
+  return { rootPath: resolvePackageBoardAssetRoot(), source: "package" };
+}
+
+export function resolveBoardAssetRoot(options: ResolveBoardAssetRootOptions = {}): BoardAssetRoot {
+  const { rootPath, source } = selectAssetRoot(options);
+
+  if (!existsSync(rootPath) || !statSync(rootPath).isDirectory()) {
+    throw new BoardAssetError("missing_asset", `Board asset root not found at ${rootPath}`, {
+      assetRoot: rootPath,
+      source,
+    });
+  }
+
+  const entryFile = resolve(rootPath, BOARD_ENTRY_FILENAME);
+  if (!existsSync(entryFile)) {
+    throw new BoardAssetError("missing_asset", `Board entry file not found at ${entryFile}`, {
+      assetRoot: rootPath,
+      entryFile,
+      source,
+      missingFile: BOARD_ENTRY_FILENAME,
+    });
+  }
+
+  return {
+    assetRoot: rootPath,
+    entryFile,
+    source,
+  };
+}

package/src/board/assets/app.js

@@ -156,7 +156,7 @@ export async function bootLegacyBoard(options = {}) {
             </div>
             <span class="${sectionLabelClasses()}">Board ready</span>
             <h1 class="mt-2 text-3xl font-semibold tracking-tight text-[var(--board-text)]">No work has been published yet</h1>
-            <p class="mx-auto mt-3 max-w-2xl text-sm leading-6 text-[var(--board-text-muted)] sm:text-base">Once the board snapshot is installed into <code class="rounded-lg border border-[var(--board-border)] bg-white/[0.04] px-2 py-1 text-[var(--board-text)]">.trekoon/board</code>, epics and tasks will appear here.</p>
+            <p class="mx-auto mt-3 max-w-2xl text-sm leading-6 text-[var(--board-text-muted)] sm:text-base">Create or sync an epic in this repository and it will appear here.</p>
           </div>
         </section>
       `;

package/src/board/event-bus.ts

@@ -18,9 +18,10 @@ export type BoardEventListener = (event: BoardEvent) => void;
 
 export interface BoardEventBus {
   publishSnapshotDelta(snapshotDelta: Record<string, unknown>): BoardDeltaEvent;
-  markInProcessWrite(timestamp?: number): void;
+  markInProcessWrite(timestamp?: number, snapshotDelta?: Record<string, unknown>): void;
   subscribe(listener: BoardEventListener): () => void;
   readonly lastInProcessWriteAt: number;
+  readonly lastInProcessSnapshotDelta: Record<string, unknown> | null;
   readonly subscriberCount: number;
   close(): void;
 }
@@ -30,6 +31,7 @@ export function createBoardEventBus(): BoardEventBus {
   let nextId = 1;
   let closed = false;
   let lastInProcessWriteAt = 0;
+  let lastInProcessSnapshotDelta: Record<string, unknown> | null = null;
 
   return {
     publishSnapshotDelta(snapshotDelta: Record<string, unknown>): BoardDeltaEvent {
@@ -54,8 +56,9 @@ export function createBoardEventBus(): BoardEventBus {
 
       return event;
     },
-    markInProcessWrite(timestamp = Date.now()): void {
+    markInProcessWrite(timestamp = Date.now(), snapshotDelta: Record<string, unknown> | undefined = undefined): void {
       lastInProcessWriteAt = timestamp;
+      lastInProcessSnapshotDelta = snapshotDelta ?? null;
     },
     subscribe(listener: BoardEventListener): () => void {
       if (closed) {
@@ -73,6 +76,9 @@ export function createBoardEventBus(): BoardEventBus {
     get lastInProcessWriteAt(): number {
       return lastInProcessWriteAt;
     },
+    get lastInProcessSnapshotDelta(): Record<string, unknown> | null {
+      return lastInProcessSnapshotDelta;
+    },
     close(): void {
       closed = true;
       listeners.clear();

package/src/board/routes.ts

@@ -214,7 +214,7 @@ function publishSnapshotDeltaIfPresent(
   const delta = readSnapshotDelta(data);
   if (delta) {
     eventBus.publishSnapshotDelta(delta);
-    eventBus.markInProcessWrite();
+    eventBus.markInProcessWrite(Date.now(), delta);
   }
 }
 

package/src/board/server.ts

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, extname, resolve } from "node:path";
 
+import { resolveBoardAssetRoot, type BoardAssetRoot } from "./asset-root";
 import { createBoardEventBus, type BoardEventBus } from "./event-bus";
 import { createBoardApiHandler } from "./routes";
 import { startWalWatcher, type WalWatcher } from "./wal-watcher";
@@ -38,6 +39,14 @@ export interface BoardServerInfo {
 export interface StartBoardServerOptions {
   readonly cwd?: string;
   readonly token?: string;
+  /**
+   * Optional override for the directory the board server reads static assets
+   * from. When unset, the server resolves the asset root via
+   * `resolveBoardAssetRoot()`, which honours `TREKOON_BOARD_ASSET_ROOT` and
+   * falls back to the assets shipped alongside the running Trekoon package.
+   * Database, API, SSE, and WAL watcher paths continue to use `cwd`.
+   */
+  readonly assetRootOverride?: string;
 }
 
 function guessContentType(pathname: string): string {
@@ -159,9 +168,20 @@ function injectBoardBootstrap(html: string, bootstrapJson: string): string {
 
 export function startBoardServer(options: StartBoardServerOptions = {}): BoardServerInfo {
   const cwd: string = options.cwd ?? process.cwd();
+  // Resolve the asset root BEFORE generating a token or opening the database.
+  // If the installed assets are missing, `resolveBoardAssetRoot` raises a
+  // `BoardAssetError` carrying only path/source metadata — never the auth
+  // token, which has not been generated yet. The CLI's `instanceof
+  // BoardAssetError` branch translates this into a clean operator error
+  // without leaking secrets through machine output or logs.
+  const assetRoot: BoardAssetRoot = resolveBoardAssetRoot(
+    options.assetRootOverride === undefined
+      ? {}
+      : { assetRootOverride: options.assetRootOverride },
+  );
+  const boardRoot: string = assetRoot.assetRoot;
   const database: TrekoonDatabase = openTrekoonDatabase(cwd);
   const paths = resolveStoragePaths(cwd);
-  const boardRoot: string = paths.boardDir;
   const stateFile: string = resolve(paths.storageDir, BOARD_SERVER_STATE_FILENAME);
   const token: string = options.token ?? randomBytes(32).toString("hex");
   const eventBus: BoardEventBus = createBoardEventBus();

package/src/board/types.ts

@@ -1,42 +1,10 @@
-export const BOARD_ASSET_CONTRACT_VERSION = "1.0.0";
-export const BOARD_BUNDLED_ASSET_DIRNAME = "assets";
-
-export interface BoardAssetManifest {
-  readonly contractVersion: string;
-  readonly assetVersion: string;
-  readonly entryFile: string;
-  readonly files: readonly string[];
-  readonly assetDigest: string;
-}
-
-export interface BoardAssetPaths {
-  readonly sourceRoot: string;
-  readonly runtimeRoot: string;
-  readonly entryFile: string;
-  readonly manifestFile: string;
-}
-
-export type BoardInstallAction = "installed" | "reinstalled" | "updated" | "unchanged";
-
-export interface BoardInstallResult {
-  readonly action: BoardInstallAction;
-  readonly paths: BoardAssetPaths;
-  readonly manifest: BoardAssetManifest;
-}
-
-export interface EnsureBoardInstalledOptions {
-  readonly workingDirectory?: string;
-  readonly assetVersion?: string;
-  readonly bundledAssetRoot?: string;
-}
-
-export class BoardInstallError extends Error {
+export class BoardAssetError extends Error {
   readonly code: string;
   readonly details: Record<string, unknown>;
 
   constructor(code: string, message: string, details: Record<string, unknown> = {}) {
     super(message);
-    this.name = "BoardInstallError";
+    this.name = "BoardAssetError";
     this.code = code;
     this.details = details;
   }

package/src/board/wal-watcher.ts

@@ -66,6 +66,65 @@ function changeKeyEqual(
   return a.version === b.version && a.updatedAt === b.updatedAt;
 }
 
+function derivedRecordFingerprint(value: unknown): string {
+  if (!value || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+
+  const record = value as Record<string, unknown>;
+  const kind = typeof record.kind === "string" ? record.kind : "";
+
+  if (kind === "task") {
+    return JSON.stringify({
+      blockedBy: record.blockedBy,
+      blocks: record.blocks,
+      dependencyIds: record.dependencyIds,
+      dependentIds: record.dependentIds,
+      subtasks: record.subtasks,
+      searchText: record.searchText,
+    });
+  }
+
+  if (kind === "subtask") {
+    return JSON.stringify({
+      blockedBy: record.blockedBy,
+      blocks: record.blocks,
+      dependencyIds: record.dependencyIds,
+      dependentIds: record.dependentIds,
+      searchText: record.searchText,
+    });
+  }
+
+  if ("taskIds" in record || "counts" in record) {
+    return JSON.stringify({
+      taskIds: record.taskIds,
+      counts: record.counts,
+      searchText: record.searchText,
+    });
+  }
+
+  return JSON.stringify(record);
+}
+
+function recordMatchesPublishedDelta(record: unknown, publishedRecord: unknown): boolean {
+  const recordKey = recordChangeKey(record);
+  const publishedKey = recordChangeKey(publishedRecord);
+  return changeKeyEqual(recordKey, publishedKey) &&
+    derivedRecordFingerprint(record) === derivedRecordFingerprint(publishedRecord);
+}
+
+function recordChanged(previousRecord: unknown, currentRecord: unknown): boolean {
+  if (!changeKeyEqual(recordChangeKey(previousRecord), recordChangeKey(currentRecord))) {
+    return true;
+  }
+
+  // The board snapshot includes derived parent fields (for example epic task
+  // counts/search text and task subtask lists). Child writes do not bump the
+  // parent row version, but those derived fields still need to reach connected
+  // boards through WAL deltas.
+  return derivedRecordFingerprint(previousRecord) !== derivedRecordFingerprint(currentRecord);
+}
+
 function diffById(previous: readonly unknown[] | undefined, current: readonly unknown[] | undefined): CollectionDiff {
   const previousIndex = new Map<string, unknown>();
   for (const record of previous ?? []) {
@@ -89,9 +148,7 @@ function diffById(previous: readonly unknown[] | undefined, current: readonly un
       upserted.push(record);
       continue;
     }
-    // Tuple compare on (version, updatedAt) — both move in lockstep on every
-    // domain write. Equal tuple → no content change → skip the upsert.
-    if (!changeKeyEqual(recordChangeKey(previousRecord), recordChangeKey(record))) {
+    if (recordChanged(previousRecord, record)) {
       upserted.push(record);
     }
   }
@@ -106,6 +163,55 @@ function diffById(previous: readonly unknown[] | undefined, current: readonly un
   return { upserted, deletedIds };
 }
 
+function recordsByIdFromDelta(delta: Record<string, unknown> | null, key: string): Map<string, unknown> {
+  const records = delta?.[key];
+  const index = new Map<string, unknown>();
+  if (!Array.isArray(records)) {
+    return index;
+  }
+
+  for (const record of records) {
+    const id = recordId(record);
+    if (id !== null) {
+      index.set(id, record);
+    }
+  }
+
+  return index;
+}
+
+function deletedIdsFromDelta(delta: Record<string, unknown> | null, key: string): Set<string> {
+  const ids = delta?.[key];
+  if (!Array.isArray(ids)) {
+    return new Set();
+  }
+
+  return new Set(ids.filter((id): id is string => typeof id === "string" && id.length > 0));
+}
+
+function suppressAlreadyPublishedDiff(
+  diff: CollectionDiff,
+  publishedRecords: Map<string, unknown>,
+  publishedDeletedIds: Set<string>,
+): CollectionDiff {
+  return {
+    upserted: diff.upserted.filter((record) => {
+      const id = recordId(record);
+      if (id === null) {
+        return true;
+      }
+
+      const publishedRecord = publishedRecords.get(id);
+      return publishedRecord === undefined || !recordMatchesPublishedDelta(record, publishedRecord);
+    }),
+    deletedIds: diff.deletedIds.filter((id) => !publishedDeletedIds.has(id)),
+  };
+}
+
+function hasDiffChanges(...diffs: readonly CollectionDiff[]): boolean {
+  return diffs.some((diff) => diff.upserted.length > 0 || diff.deletedIds.length > 0);
+}
+
 function readMtime(path: string): number {
   if (!existsSync(path)) {
     return 0;
@@ -188,27 +294,52 @@ export function startWalWatcher(options: WalWatcherOptions): WalWatcher {
       return;
     }
     const inProcessWriteAt = options.eventBus.lastInProcessWriteAt;
-    if (
+    const shouldSuppressInProcessTick =
       inProcessWriteAt > lastSuppressedInProcessWriteAt &&
-      Date.now() - inProcessWriteAt <= IN_PROCESS_WAL_SUPPRESS_MS
-    ) {
-      lastSuppressedInProcessWriteAt = inProcessWriteAt;
-      return;
-    }
+      Date.now() - inProcessWriteAt <= IN_PROCESS_WAL_SUPPRESS_MS;
 
     try {
       const fresh = buildSnapshot(domain);
-
       const epicsDiff = diffById(lastSnapshot.epics, fresh.epics);
       const tasksDiff = diffById(lastSnapshot.tasks, fresh.tasks);
       const subtasksDiff = diffById(lastSnapshot.subtasks, fresh.subtasks);
       const dependenciesDiff = diffById(lastSnapshot.dependencies, fresh.dependencies);
 
-      const hasChanges =
-        epicsDiff.upserted.length > 0 || epicsDiff.deletedIds.length > 0 ||
-        tasksDiff.upserted.length > 0 || tasksDiff.deletedIds.length > 0 ||
-        subtasksDiff.upserted.length > 0 || subtasksDiff.deletedIds.length > 0 ||
-        dependenciesDiff.upserted.length > 0 || dependenciesDiff.deletedIds.length > 0;
+      const shouldSuppressDiff = shouldSuppressInProcessTick
+        ? {
+            epics: suppressAlreadyPublishedDiff(
+              epicsDiff,
+              recordsByIdFromDelta(options.eventBus.lastInProcessSnapshotDelta, "epics"),
+              deletedIdsFromDelta(options.eventBus.lastInProcessSnapshotDelta, "deletedEpicIds"),
+            ),
+            tasks: suppressAlreadyPublishedDiff(
+              tasksDiff,
+              recordsByIdFromDelta(options.eventBus.lastInProcessSnapshotDelta, "tasks"),
+              deletedIdsFromDelta(options.eventBus.lastInProcessSnapshotDelta, "deletedTaskIds"),
+            ),
+            subtasks: suppressAlreadyPublishedDiff(
+              subtasksDiff,
+              recordsByIdFromDelta(options.eventBus.lastInProcessSnapshotDelta, "subtasks"),
+              deletedIdsFromDelta(options.eventBus.lastInProcessSnapshotDelta, "deletedSubtaskIds"),
+            ),
+            dependencies: suppressAlreadyPublishedDiff(
+              dependenciesDiff,
+              recordsByIdFromDelta(options.eventBus.lastInProcessSnapshotDelta, "dependencies"),
+              deletedIdsFromDelta(options.eventBus.lastInProcessSnapshotDelta, "deletedDependencyIds"),
+            ),
+          }
+        : null;
+
+      if (shouldSuppressInProcessTick) {
+        lastSuppressedInProcessWriteAt = inProcessWriteAt;
+      }
+
+      const publishEpicsDiff = shouldSuppressDiff?.epics ?? epicsDiff;
+      const publishTasksDiff = shouldSuppressDiff?.tasks ?? tasksDiff;
+      const publishSubtasksDiff = shouldSuppressDiff?.subtasks ?? subtasksDiff;
+      const publishDependenciesDiff = shouldSuppressDiff?.dependencies ?? dependenciesDiff;
+
+      const hasChanges = hasDiffChanges(publishEpicsDiff, publishTasksDiff, publishSubtasksDiff, publishDependenciesDiff);
 
       lastSnapshot = fresh;
 
@@ -219,14 +350,14 @@ export function startWalWatcher(options: WalWatcherOptions): WalWatcher {
       options.eventBus.publishSnapshotDelta({
         generatedAt: Date.now(),
         source: "wal-watcher",
-        epics: epicsDiff.upserted,
-        tasks: tasksDiff.upserted,
-        subtasks: subtasksDiff.upserted,
-        dependencies: dependenciesDiff.upserted,
-        deletedEpicIds: epicsDiff.deletedIds,
-        deletedTaskIds: tasksDiff.deletedIds,
-        deletedSubtaskIds: subtasksDiff.deletedIds,
-        deletedDependencyIds: dependenciesDiff.deletedIds,
+        epics: publishEpicsDiff.upserted,
+        tasks: publishTasksDiff.upserted,
+        subtasks: publishSubtasksDiff.upserted,
+        dependencies: publishDependenciesDiff.upserted,
+        deletedEpicIds: publishEpicsDiff.deletedIds,
+        deletedTaskIds: publishTasksDiff.deletedIds,
+        deletedSubtaskIds: publishSubtasksDiff.deletedIds,
+        deletedDependencyIds: publishDependenciesDiff.deletedIds,
       });
     } catch (error) {
       // Reconciliation must never crash the server. Errors here usually mean

package/src/commands/board.ts

@@ -1,9 +1,9 @@
 import { parseArgs, readUnexpectedPositionals } from "./arg-parser";
 
-import { ensureBoardInstalled, updateBoardInstallation } from "../board/install";
+import { resolveBoardAssetRoot, type BoardAssetRoot, type ResolveBoardAssetRootOptions } from "../board/asset-root";
 import { openBoardInBrowser, type OpenBrowserResult } from "../board/open-browser";
 import { startBoardServer, type BoardServerInfo } from "../board/server";
-import { BoardInstallError, type EnsureBoardInstalledOptions } from "../board/types";
+import { BoardAssetError } from "../board/types";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 
@@ -11,26 +11,23 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 // command modules: each subcommand declares the set of flags (and options)
 // it accepts; everything else is rejected up-front.
 const OPEN_FLAGS = ["reveal-token"] as const;
-const UPDATE_FLAGS: readonly string[] = [];
 
 const FLAGS_BY_SUBCOMMAND: Readonly<Record<string, readonly string[]>> = {
   open: OPEN_FLAGS,
-  update: UPDATE_FLAGS,
 };
 
-type EnsureBoardInstalledFn = (options: EnsureBoardInstalledOptions) => ReturnType<typeof ensureBoardInstalled>;
-type StartBoardServerFn = (options: { cwd: string }) => BoardServerInfo;
+type ResolveAssetRootFn = (options: ResolveBoardAssetRootOptions) => BoardAssetRoot;
+type StartBoardServerFn = (options: { cwd: string; assetRootOverride?: string }) => BoardServerInfo;
 type OpenBoardInBrowserFn = (url: string) => Promise<OpenBrowserResult> | OpenBrowserResult;
 
-let ensureInstalledImpl: EnsureBoardInstalledFn = ensureBoardInstalled;
-let updateInstalledImpl: EnsureBoardInstalledFn = updateBoardInstallation;
+let resolveAssetRootImpl: ResolveAssetRootFn = resolveBoardAssetRoot;
 let startBoardServerImpl: StartBoardServerFn = (options) => startBoardServer(options);
 let openBoardInBrowserImpl: OpenBoardInBrowserFn = openBoardInBrowser;
 
 function usageResult(): CliResult {
   return failResult({
     command: "board",
-    human: "Usage: trekoon board <open|update>",
+    human: "Usage: trekoon board <open>",
     data: {},
     error: {
       code: "invalid_subcommand",
@@ -39,15 +36,7 @@ function usageResult(): CliResult {
   });
 }
 
-function boardInstallOptions(context: CliContext): EnsureBoardInstalledOptions {
-  const bundledAssetRoot: string | undefined = process.env.TREKOON_BOARD_ASSET_ROOT;
-  return {
-    workingDirectory: context.cwd,
-    ...(bundledAssetRoot === undefined ? {} : { bundledAssetRoot }),
-  };
-}
-
-function boardInstallFailure(command: string, error: BoardInstallError): CliResult {
+function boardAssetFailure(command: string, error: BoardAssetError): CliResult {
   return failResult({
     command,
     human: error.message,
@@ -63,13 +52,11 @@ function boardInstallFailure(command: string, error: BoardInstallError): CliResu
 }
 
 export function setBoardCommandHooksForTests(hooks: {
-  ensureInstalled?: EnsureBoardInstalledFn;
-  updateInstalled?: EnsureBoardInstalledFn;
+  resolveAssetRoot?: ResolveAssetRootFn;
   startBoardServer?: StartBoardServerFn;
   openBoardInBrowser?: OpenBoardInBrowserFn;
 } | null): void {
-  ensureInstalledImpl = hooks?.ensureInstalled ?? ensureBoardInstalled;
-  updateInstalledImpl = hooks?.updateInstalled ?? updateBoardInstallation;
+  resolveAssetRootImpl = hooks?.resolveAssetRoot ?? resolveBoardAssetRoot;
   startBoardServerImpl = hooks?.startBoardServer ?? ((options) => startBoardServer(options));
   openBoardInBrowserImpl = hooks?.openBoardInBrowser ?? openBoardInBrowser;
 }
@@ -121,21 +108,12 @@ export async function runBoard(context: CliContext): Promise<CliResult> {
 
   try {
     switch (subcommand) {
-      case "update": {
-        const install = updateInstalledImpl(boardInstallOptions(context));
-        return okResult({
-          command: "board.update",
-          human: `Board assets ${install.action} at ${install.paths.runtimeRoot}`,
-          data: {
-            action: install.action,
-            paths: install.paths,
-            manifest: install.manifest,
-          },
-        });
-      }
       case "open": {
-        const install = ensureInstalledImpl(boardInstallOptions(context));
-        const server = startBoardServerImpl({ cwd: context.cwd });
+        const assetRoot = resolveAssetRootImpl({});
+        const server = startBoardServerImpl({
+          cwd: context.cwd,
+          assetRootOverride: assetRoot.assetRoot,
+        });
         const launch = await openBoardInBrowserImpl(server.url);
         const humanLines: string[] = [
           `Board ready at ${server.fallbackUrl}`,
@@ -170,10 +148,10 @@ export async function runBoard(context: CliContext): Promise<CliResult> {
           command: "board.open",
           human: humanLines.join("\n"),
           data: {
-            install: {
-              action: install.action,
-              paths: install.paths,
-              manifest: install.manifest,
+            assetRoot: {
+              path: assetRoot.assetRoot,
+              entryFile: assetRoot.entryFile,
+              source: assetRoot.source,
             },
             server: serverData,
             launch: launchData,
@@ -184,8 +162,8 @@ export async function runBoard(context: CliContext): Promise<CliResult> {
         return usageResult();
     }
   } catch (error: unknown) {
-    if (error instanceof BoardInstallError) {
-      return boardInstallFailure(`board.${subcommand}`, error);
+    if (error instanceof BoardAssetError) {
+      return boardAssetFailure(`board.${subcommand}`, error);
     }
 
     throw error;

package/src/commands/help.ts

@@ -22,7 +22,7 @@ const ROOT_HELP = [
   "  init         Create or re-bootstrap .trekoon storage",
   "  quickstart   Storage model, agent loop, and common patterns",
   "  wipe         Delete repo-wide .trekoon state (requires --yes)",
-  "  board        Open or update the local board",
+  "  board        Open the local board",
   "  epic         Create, list, update, search, and track epics",
   "  task         Create, list, update, search, and complete tasks",
   "  subtask      Create, list, update, and search subtasks",
@@ -89,12 +89,12 @@ const WIPE_HELP = [
 ].join("\n");
 
 const BOARD_HELP = [
-  "Usage: trekoon board <open|update>",
+  "Usage: trekoon board <open>",
   "",
   "Subcommands:",
-  "  open    Install board assets, start a local server on 127.0.0.1,",
-  "          and open the browser. Returns the board URL and a fallback URL.",
-  "  update  Refresh board runtime assets only. No server, no browser.",
+  "  open    Start a local board server on 127.0.0.1 and open the browser.",
+  "          Returns the board URL and a fallback URL. Board assets are served",
+  "          directly from the running Trekoon package; no per-repo install.",
   "",
   "Token visibility:",
   "  By default the board token is redacted from machine output (shown as ****).",
@@ -108,7 +108,6 @@ const BOARD_HELP = [
   "Examples:",
   "  trekoon board open",
   "  trekoon board open --reveal-token",
-  "  trekoon --json board update",
 ].join("\n");
 
 const EPIC_HELP = [

package/src/commands/init.ts

@@ -3,8 +3,6 @@ import { resolve } from "node:path";
 
 import { unexpectedFailureResult } from "./error-utils";
 
-import { ensureBoardInstalled } from "../board/install";
-import { BoardInstallError } from "../board/types";
 import { DomainError } from "../domain/types";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
@@ -108,11 +106,6 @@ export async function runInit(context: CliContext): Promise<CliResult> {
   try {
     database = openTrekoonDatabase(context.cwd);
     const diagnostics = database.diagnostics;
-    const bundledAssetRoot: string | undefined = process.env.TREKOON_BOARD_ASSET_ROOT;
-    const board = ensureBoardInstalled({
-      workingDirectory: context.cwd,
-      ...(bundledAssetRoot === undefined ? {} : { bundledAssetRoot }),
-    });
     const gitignoreAction: GitignoreAction = ensureGitignore(
       database.paths.storageDir,
       diagnostics.storageMode,
@@ -125,8 +118,6 @@ export async function runInit(context: CliContext): Promise<CliResult> {
       `Shared storage root: ${diagnostics.sharedStorageRoot}`,
       `Storage directory: ${database.paths.storageDir}`,
       `Database file: ${database.paths.databaseFile}`,
-      `Board assets: ${board.action}`,
-      `Board runtime root: ${board.paths.runtimeRoot}`,
       `Gitignore: ${gitignoreAction}`,
       ...buildRecoverySummary(database),
     ];
@@ -142,11 +133,6 @@ export async function runInit(context: CliContext): Promise<CliResult> {
         sharedStorageRoot: diagnostics.sharedStorageRoot,
         storageDir: database.paths.storageDir,
         databaseFile: database.paths.databaseFile,
-        board: {
-          action: board.action,
-          paths: board.paths,
-          manifest: board.manifest,
-        },
         gitignore: {
           action: gitignoreAction,
           path: resolve(database.paths.storageDir, ".gitignore"),
@@ -170,21 +156,6 @@ export async function runInit(context: CliContext): Promise<CliResult> {
       }
     }
 
-    if (error instanceof BoardInstallError) {
-      return failResult({
-        command: "init",
-        human: error.message,
-        data: {
-          code: error.code,
-          ...error.details,
-        },
-        error: {
-          code: error.code,
-          message: error.message,
-        },
-      });
-    }
-
     return unexpectedFailureResult(error, {
       command: "init",
       human: "Unexpected init command failure",

package/src/commands/quickstart.ts

@@ -32,7 +32,7 @@ const QUICKSTART_TEXT = [
   "  stop and fix the setup before continuing.",
   "",
   "  Manual bootstrap (step by step):",
-  "    trekoon --toon init",
+  "    trekoon --toon init       # creates .trekoon/ shared storage (no board assets copied)",
   "    trekoon --toon sync status",
   "    trekoon --toon task next",
   "",

package/src/runtime/version.ts

@@ -1,11 +1,19 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 interface PackageManifest {
   readonly version?: string;
 }
 
 function readCliVersion(): string {
-  const packageJsonPath = new URL("../../package.json", import.meta.url);
+  const packageJsonPath = [
+    new URL("../../package.json", import.meta.url),
+    new URL("./package.json", import.meta.url),
+  ].find((candidate: URL): boolean => existsSync(candidate));
+
+  if (packageJsonPath === undefined) {
+    throw new Error("package.json is missing from the Trekoon runtime bundle.");
+  }
+
   const packageJsonContent: string = readFileSync(packageJsonPath, "utf8");
   const packageManifest: PackageManifest = JSON.parse(packageJsonContent) as PackageManifest;
   const version: string | undefined = packageManifest.version;

package/src/storage/path.ts

@@ -4,9 +4,6 @@ import { resolve } from "node:path";
 
 export const TREKOON_STORAGE_DIRNAME = ".trekoon";
 export const TREKOON_DATABASE_FILENAME = "trekoon.db";
-export const TREKOON_BOARD_DIRNAME = "board";
-export const TREKOON_BOARD_ENTRY_FILENAME = "index.html";
-export const TREKOON_BOARD_MANIFEST_FILENAME = "manifest.json";
 
 export function resolveLegacyWorktreeStorageDir(worktreeRoot: string): string {
   return resolve(worktreeRoot, TREKOON_STORAGE_DIRNAME);
@@ -18,18 +15,6 @@ export function resolveLegacyWorktreeDatabaseFile(worktreeRoot: string): string
 
 export type StorageMode = "cwd" | "git_common_dir";
 
-export function resolveBoardStorageDir(storageDir: string): string {
-  return resolve(storageDir, TREKOON_BOARD_DIRNAME);
-}
-
-export function resolveBoardEntryFile(storageDir: string): string {
-  return resolve(resolveBoardStorageDir(storageDir), TREKOON_BOARD_ENTRY_FILENAME);
-}
-
-export function resolveBoardManifestFile(storageDir: string): string {
-  return resolve(resolveBoardStorageDir(storageDir), TREKOON_BOARD_MANIFEST_FILENAME);
-}
-
 export interface StoragePaths {
   readonly invocationCwd: string;
   readonly storageMode: StorageMode;
@@ -38,9 +23,6 @@ export interface StoragePaths {
   readonly sharedStorageRoot: string;
   readonly storageDir: string;
   readonly databaseFile: string;
-  readonly boardDir: string;
-  readonly boardEntryFile: string;
-  readonly boardManifestFile: string;
   readonly diagnostics: StoragePathDiagnostics;
 }
 
@@ -53,9 +35,6 @@ export interface StoragePathIssue {
   readonly worktreeRoot: string;
   readonly sharedStorageRoot: string;
   readonly databaseFile: string;
-  readonly boardDir: string;
-  readonly boardEntryFile: string;
-  readonly boardManifestFile: string;
 }
 
 export interface StoragePathDiagnostics {
@@ -65,9 +44,6 @@ export interface StoragePathDiagnostics {
   readonly worktreeRoot: string;
   readonly sharedStorageRoot: string;
   readonly databaseFile: string;
-  readonly boardDir: string;
-  readonly boardEntryFile: string;
-  readonly boardManifestFile: string;
   readonly warnings: readonly StoragePathIssue[];
   readonly errors: readonly StoragePathIssue[];
 }
@@ -115,9 +91,6 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
   const sharedStorageRoot: string = repoCommonDir ? realpathSync(resolve(repoCommonDir, "..")) : invocationCwd;
   const storageDir: string = resolve(sharedStorageRoot, TREKOON_STORAGE_DIRNAME);
   const databaseFile: string = resolve(storageDir, TREKOON_DATABASE_FILENAME);
-  const boardDir: string = resolveBoardStorageDir(storageDir);
-  const boardEntryFile: string = resolveBoardEntryFile(storageDir);
-  const boardManifestFile: string = resolveBoardManifestFile(storageDir);
   const warnings: StoragePathIssue[] = [];
 
   const createIssue = (code: string, message: string): StoragePathIssue => ({
@@ -129,9 +102,6 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
     worktreeRoot,
     sharedStorageRoot,
     databaseFile,
-    boardDir,
-    boardEntryFile,
-    boardManifestFile,
   });
 
   if (invocationCwd !== worktreeRoot) {
@@ -156,9 +126,6 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
     worktreeRoot,
     sharedStorageRoot,
     databaseFile,
-    boardDir,
-    boardEntryFile,
-    boardManifestFile,
     warnings,
     errors: [],
   };
@@ -171,9 +138,6 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
     sharedStorageRoot,
     storageDir,
     databaseFile,
-    boardDir,
-    boardEntryFile,
-    boardManifestFile,
     diagnostics,
   };
 

package/src/board/install.ts

@@ -1,196 +0,0 @@
-import {
-  createHash,
-} from "node:crypto";
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { CLI_VERSION } from "../runtime/version";
-import {
-  resolveStoragePaths,
-  TREKOON_BOARD_ENTRY_FILENAME,
-  TREKOON_BOARD_MANIFEST_FILENAME,
-} from "../storage/path";
-import {
-  BOARD_ASSET_CONTRACT_VERSION,
-  BOARD_BUNDLED_ASSET_DIRNAME,
-  BoardInstallError,
-  type BoardAssetManifest,
-  type BoardInstallAction,
-  type BoardInstallResult,
-  type EnsureBoardInstalledOptions,
-} from "./types";
-
-function resolveBundledBoardAssetRoot(): string {
-  return fileURLToPath(new URL(`./${BOARD_BUNDLED_ASSET_DIRNAME}`, import.meta.url));
-}
-
-function listRelativeFiles(rootPath: string, currentPath: string = rootPath): string[] {
-  const entries = readdirSync(currentPath, { withFileTypes: true });
-  const files: string[] = [];
-
-  for (const entry of entries) {
-    const entryPath: string = join(currentPath, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...listRelativeFiles(rootPath, entryPath));
-      continue;
-    }
-
-    if (entry.isFile()) {
-      files.push(relative(rootPath, entryPath));
-    }
-  }
-
-  return files.sort((left, right) => left.localeCompare(right));
-}
-
-interface ReadManifestResult {
-  readonly manifest: BoardAssetManifest | null;
-  readonly damaged: boolean;
-}
-
-function readManifest(manifestFile: string): ReadManifestResult {
-  if (!existsSync(manifestFile)) {
-    return {
-      manifest: null,
-      damaged: false,
-    };
-  }
-
-  try {
-    const rawManifest: string = readFileSync(manifestFile, "utf8");
-    return {
-      manifest: JSON.parse(rawManifest) as BoardAssetManifest,
-      damaged: false,
-    };
-  } catch {
-    return {
-      manifest: null,
-      damaged: true,
-    };
-  }
-}
-
-function createAssetDigest(sourceRoot: string, files: readonly string[]): string {
-  const hash = createHash("sha256");
-
-  for (const relativeFile of files) {
-    hash.update(relativeFile);
-    hash.update("\0");
-    hash.update(readFileSync(join(sourceRoot, relativeFile)));
-    hash.update("\0");
-  }
-
-  return hash.digest("hex");
-}
-
-function createManifest(sourceRoot: string, assetVersion: string, files: readonly string[]): BoardAssetManifest {
-  return {
-    contractVersion: BOARD_ASSET_CONTRACT_VERSION,
-    assetVersion,
-    entryFile: TREKOON_BOARD_ENTRY_FILENAME,
-    files,
-    assetDigest: createAssetDigest(sourceRoot, files),
-  };
-}
-
-function installBoardFiles(sourceRoot: string, runtimeRoot: string, manifest: BoardAssetManifest): void {
-  rmSync(runtimeRoot, { recursive: true, force: true });
-  mkdirSync(dirname(runtimeRoot), { recursive: true });
-  cpSync(sourceRoot, runtimeRoot, { recursive: true });
-  writeFileSync(join(runtimeRoot, TREKOON_BOARD_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-}
-
-function determineAction(
-  runtimeRoot: string,
-  entryFile: string,
-  currentManifest: BoardAssetManifest | null,
-  manifestDamaged: boolean,
-  nextManifest: BoardAssetManifest,
-): BoardInstallAction {
-  if (manifestDamaged) {
-    return "reinstalled";
-  }
-
-  if (!existsSync(runtimeRoot) || !existsSync(entryFile) || currentManifest === null) {
-    return currentManifest === null && !existsSync(runtimeRoot) ? "installed" : "reinstalled";
-  }
-
-  if (
-    currentManifest.contractVersion !== nextManifest.contractVersion ||
-    currentManifest.assetVersion !== nextManifest.assetVersion ||
-    currentManifest.entryFile !== nextManifest.entryFile ||
-    JSON.stringify(currentManifest.files) !== JSON.stringify(nextManifest.files) ||
-    currentManifest.assetDigest !== nextManifest.assetDigest
-  ) {
-    return "updated";
-  }
-
-  for (const relativeFile of nextManifest.files) {
-    if (!existsSync(join(runtimeRoot, relativeFile))) {
-      return "reinstalled";
-    }
-  }
-
-  return "unchanged";
-}
-
-export function ensureBoardInstalled(options: EnsureBoardInstalledOptions = {}): BoardInstallResult {
-  const paths = resolveStoragePaths(options.workingDirectory);
-  const sourceRoot: string = resolve(options.bundledAssetRoot ?? resolveBundledBoardAssetRoot());
-  const runtimeRoot: string = paths.boardDir;
-  const entryFile: string = paths.boardEntryFile;
-  const manifestFile: string = paths.boardManifestFile;
-
-  if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) {
-    throw new BoardInstallError("missing_asset", `Bundled board asset directory not found at ${sourceRoot}`, {
-      sourceRoot,
-    });
-  }
-
-  const sourceFiles: string[] = listRelativeFiles(sourceRoot);
-  if (!sourceFiles.includes(TREKOON_BOARD_ENTRY_FILENAME)) {
-    throw new BoardInstallError("missing_asset", `Bundled board entry file not found at ${join(sourceRoot, TREKOON_BOARD_ENTRY_FILENAME)}`, {
-      sourceRoot,
-      missingFile: TREKOON_BOARD_ENTRY_FILENAME,
-    });
-  }
-
-  const manifest: BoardAssetManifest = createManifest(sourceRoot, options.assetVersion ?? CLI_VERSION, sourceFiles);
-  const currentManifestResult: ReadManifestResult = readManifest(manifestFile);
-  const action: BoardInstallAction = determineAction(
-    runtimeRoot,
-    entryFile,
-    currentManifestResult.manifest,
-    currentManifestResult.damaged,
-    manifest,
-  );
-
-  if (action !== "unchanged") {
-    installBoardFiles(sourceRoot, runtimeRoot, manifest);
-  }
-
-  return {
-    action,
-    paths: {
-      sourceRoot,
-      runtimeRoot,
-      entryFile,
-      manifestFile,
-    },
-    manifest,
-  };
-}
-
-export function updateBoardInstallation(options: EnsureBoardInstalledOptions = {}): BoardInstallResult {
-  return ensureBoardInstalled(options);
-}