trekoon 0.4.2 → 0.4.4

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 {
@@ -90,7 +99,7 @@ function isUnavailablePortError(error: unknown): boolean {
 }
 
 function buildBoardSessionCookie(token: string): string {
-  return `trekoon_board_session=${encodeURIComponent(token)}; Path=/; SameSite=Strict; HttpOnly`;
+  return `trekoon_board_session=${encodeURIComponent(token)}; Path=/; Max-Age=86400; SameSite=Strict; HttpOnly`;
 }
 
 function readBoardSessionCookie(request: Request): string | null {
@@ -122,6 +131,13 @@ function isAuthenticatedBoardRequest(request: Request, url: URL, token: string):
   return cookieToken !== null && cookieToken === token;
 }
 
+function buildTokenStrippedLocation(url: URL): string {
+  const redirectUrl = new URL(url);
+  redirectUrl.searchParams.delete("token");
+  const pathname = `/${redirectUrl.pathname.replace(/^\/+/u, "")}`;
+  return `${pathname}${redirectUrl.search}${redirectUrl.hash}`;
+}
+
 function serializeInlineJson(value: unknown): string {
   return JSON.stringify(value)
     .replace(/</g, "\\u003c")
@@ -152,11 +168,22 @@ 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(18).toString("hex");
+  const token: string = options.token ?? randomBytes(32).toString("hex");
   const eventBus: BoardEventBus = createBoardEventBus();
   const walWatcher: WalWatcher = startWalWatcher({
     db: database.db,
@@ -195,15 +222,15 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
           // and Referer headers free of the secret on the very first
           // navigation, severing the leakage surface that an open URL bar
           // would otherwise expose. The cookie carries auth from here on.
-          const redirectUrl = new URL(url);
-          redirectUrl.searchParams.delete("token");
-          // Preserve the relative location so the redirect works regardless
-          // of how the client reached us (loopback IP vs. localhost name).
-          const location = `${redirectUrl.pathname}${redirectUrl.search}${redirectUrl.hash}`;
+          // Preserve a single-slash relative location so the redirect works
+          // regardless of how the client reached us, without creating a
+          // scheme-relative `//host` Location for odd incoming paths.
+          const location = buildTokenStrippedLocation(url);
           return new Response(null, {
             status: 302,
             headers: {
               ...responseHeaders,
+              "referrer-policy": "no-referrer",
               location: location.length > 0 ? location : "/",
             },
           });

package/src/board/snapshot.ts

@@ -34,6 +34,7 @@ interface BoardSnapshotSubtask {
   readonly owner: string | null;
   readonly createdAt: number;
   readonly updatedAt: number;
+  readonly version: number;
   readonly blockedBy: readonly string[];
   readonly blocks: readonly string[];
   readonly dependencyIds: readonly string[];
@@ -51,6 +52,7 @@ interface BoardSnapshotTask {
   readonly owner: string | null;
   readonly createdAt: number;
   readonly updatedAt: number;
+  readonly version: number;
   readonly blockedBy: readonly string[];
   readonly blocks: readonly string[];
   readonly dependencyIds: readonly string[];
@@ -66,6 +68,7 @@ interface BoardSnapshotEpic {
   readonly status: string;
   readonly createdAt: number;
   readonly updatedAt: number;
+  readonly version: number;
   readonly taskIds: readonly string[];
   readonly counts: FlatCounts;
   readonly searchText: string;
@@ -169,6 +172,7 @@ function mapSnapshotSubtask(subtask: SubtaskRecord, indexes: ReturnType<typeof b
     owner: subtask.owner ?? null,
     createdAt: subtask.createdAt,
     updatedAt: subtask.updatedAt,
+    version: subtask.version,
     blockedBy: indexes.blockedByIdsBySource.get(subtask.id) ?? [],
     blocks: indexes.blocksByTarget.get(subtask.id) ?? [],
     dependencyIds: indexes.dependencyIdsBySource.get(subtask.id) ?? [],
@@ -188,6 +192,7 @@ function mapSnapshotTask(task: TaskRecord, taskSubtasks: readonly BoardSnapshotS
     owner: task.owner ?? null,
     createdAt: task.createdAt,
     updatedAt: task.updatedAt,
+    version: task.version,
     blockedBy: indexes.blockedByIdsBySource.get(task.id) ?? [],
     blocks: indexes.blocksByTarget.get(task.id) ?? [],
     dependencyIds: indexes.dependencyIdsBySource.get(task.id) ?? [],
@@ -205,6 +210,7 @@ function mapSnapshotEpic(epic: EpicRecord, epicTasks: readonly BoardSnapshotTask
     status: epic.status,
     createdAt: epic.createdAt,
     updatedAt: epic.updatedAt,
+    version: epic.version,
     taskIds: epicTasks.map((task) => task.id),
     counts: deriveFlatCounts(epicTasks),
     searchText: [epic.title, epic.description, ...epicTasks.map((task) => task.searchText)].join(" ").toLowerCase(),

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

@@ -22,6 +22,8 @@ import { TrackerDomain } from "../domain/tracker-domain";
 import { type BoardEventBus } from "./event-bus";
 import { buildBoardSnapshot, type BoardSnapshot } from "./snapshot";
 
+const IN_PROCESS_WAL_SUPPRESS_MS = 500;
+
 interface CollectionDiff {
   readonly upserted: unknown[];
   readonly deletedIds: string[];
@@ -64,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 ?? []) {
@@ -87,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);
     }
   }
@@ -104,6 +163,66 @@ 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;
+  }
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
 export interface WalWatcherOptions {
   readonly db: Database;
   readonly databaseFile: string;
@@ -168,25 +287,59 @@ export function startWalWatcher(options: WalWatcherOptions): WalWatcher {
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let closed = false;
   let failures = 0;
+  let lastSuppressedInProcessWriteAt = 0;
 
   function reconcile(): void {
     if (closed) {
       return;
     }
+    const inProcessWriteAt = options.eventBus.lastInProcessWriteAt;
+    const shouldSuppressInProcessTick =
+      inProcessWriteAt > lastSuppressedInProcessWriteAt &&
+      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;
 
@@ -197,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
@@ -235,17 +388,6 @@ export function startWalWatcher(options: WalWatcherOptions): WalWatcher {
   // than spurious watcher fires (e.g. atime-only updates on some filesystems).
   let lastWalMtime: number = readMtime(walFile);
 
-  function readMtime(path: string): number {
-    if (!existsSync(path)) {
-      return 0;
-    }
-    try {
-      return statSync(path).mtimeMs;
-    } catch {
-      return 0;
-    }
-  }
-
   function maybeScheduleReconcile(): void {
     const currentMtime = readMtime(walFile);
     // mtime can equal 0 when the WAL was just checkpointed and removed; treat

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,20 +108,19 @@ const BOARD_HELP = [
   "Examples:",
   "  trekoon board open",
   "  trekoon board open --reveal-token",
-  "  trekoon --json board update",
 ].join("\n");
 
 const EPIC_HELP = [
   "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress|export> [options]",
   "",
   "Create:",
-  "  trekoon epic create --title \"...\" --description \"...\" [--status <status>]",
-  "  trekoon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  trekoon --toon epic create --title \"...\" --description \"...\" [--status <status>]",
+  "  trekoon --toon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
   "  When the full tree is known, the second form creates everything in one shot",
   "  and returns mappings/counts. Same compact spec grammar as epic expand.",
   "",
   "Expand:",
-  "  trekoon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  trekoon --toon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
   "  --task <temp-key>|<title>|<description>|<status>",
   `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>  (${"@"}<temp-key> for new parents)`,
   `  --dep <source-ref>|<depends-on-ref>  (refs can be IDs or ${"@"}<temp-key>)`,
@@ -441,8 +440,8 @@ const SUGGEST_HELP = [
 
 const SKILLS_HELP = [
   "Usage:",
-  "  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",
   "",
   "Installs or refreshes the Trekoon skill so AI agents can plan and execute.",
@@ -451,7 +450,7 @@ const SKILLS_HELP = [
   "  Creates a symlink at .agents/skills/trekoon pointing to the bundled source,",
   "  so the skill always matches the installed CLI version.",
   "  --link            Also create an editor symlink named 'trekoon'.",
-  "  --editor <name>   Required with --link (opencode|claude|pi).",
+  "  --editor <name>   Required with --link (opencode|claude|codex|pi).",
   "  --to <path>       Override the symlink root for --link only.",
   "  --allow-outside-repo  Allow links outside the repo (requires --link).",
   "",