veryfront 0.1.49 → 0.1.51

package/src/src/sandbox/index.ts

@@ -8,7 +8,7 @@
  * ```ts
  * import { Sandbox } from "veryfront/sandbox";
  *
- * const sandbox = await Sandbox.create({ authToken: "<your-jwt>" });
+ * const sandbox = await Sandbox.create();
  * const result = await sandbox.executeCommand("echo hello");
  * console.log(result.stdout); // "hello\n"
  * await sandbox.close();

package/src/src/sandbox/sandbox.ts

@@ -6,15 +6,25 @@
  *
  * @module
  */
-
-/** Options for creating a sandbox session. */
 import * as dntShim from "../../_dnt.shims.js";
 
+
+import {
+  createError,
+  INITIALIZATION_ERROR,
+  REQUEST_ERROR,
+  TIMEOUT_ERROR,
+  toError,
+} from "../errors/index.js";
+import { getVeryfrontCloudAuthToken } from "../platform/cloud/resolver.js";
+import { getHostEnv } from "../platform/compat/process.js";
+
+/** Options for creating a sandbox session. */
 export interface SandboxOptions {
   /** Base URL of the Veryfront API. Defaults to VERYFRONT_API_URL env. */
   apiUrl?: string;
-  /** User's JWT for authentication. */
-  authToken: string;
+  /** Explicit Veryfront auth token or API key override. */
+  authToken?: string;
 }
 
 /** Result of a command execution: stdout, stderr, and exit code. */
@@ -40,54 +50,71 @@ export class Sandbox {
     private apiUrl: string,
   ) {}
 
-  private static resolveApiUrl(options: SandboxOptions): string {
+  private static resolveApiUrl(options: SandboxOptions = {}): string {
     return options.apiUrl ||
-      (typeof dntShim.Deno !== "undefined"
-        ? dntShim.Deno.env.get("VERYFRONT_API_URL")
-        : process.env.VERYFRONT_API_URL) ||
+      getHostEnv("VERYFRONT_API_URL") ||
       "https://api.veryfront.com";
   }
 
+  private static resolveAuthToken(options: SandboxOptions = {}): string {
+    const authToken = options.authToken?.trim() || getVeryfrontCloudAuthToken();
+    if (authToken) return authToken;
+
+    throw toError(
+      createError({
+        type: "config",
+        message:
+          "Sandbox auth not configured. Set VERYFRONT_API_TOKEN, provide request-scoped Veryfront credentials, or pass authToken explicitly.",
+      }),
+    );
+  }
+
   /** Create a new sandbox session. Claims a warm pod or creates a new one. */
-  static async create(options: SandboxOptions): Promise<Sandbox> {
+  static async create(options: SandboxOptions = {}): Promise<Sandbox> {
     const apiUrl = Sandbox.resolveApiUrl(options);
+    const authToken = Sandbox.resolveAuthToken(options);
 
     const res = await dntShim.fetch(`${apiUrl}/sandbox-sessions`, {
       method: "POST",
       headers: {
-        Authorization: `Bearer ${options.authToken}`,
+        Authorization: `Bearer ${authToken}`,
         "Content-Type": "application/json",
       },
     });
 
     if (!res.ok) {
-      throw new Error(`Failed to create sandbox: ${res.status} ${await res.text()}`);
+      throw REQUEST_ERROR.create({
+        detail: `Failed to create sandbox: ${res.status} ${await res.text()}`,
+      });
     }
 
     const { id, endpoint, status } = await res.json();
 
     // If not yet running, poll until ready
     if (status !== "running") {
-      await Sandbox.waitForReady(apiUrl, id, options.authToken);
+      await Sandbox.waitForReady(apiUrl, id, authToken);
     }
 
-    return new Sandbox(endpoint, id, options.authToken, apiUrl);
+    return new Sandbox(endpoint, id, authToken, apiUrl);
   }
 
   /** Reconnect to an existing sandbox session. */
-  static async get(id: string, options: SandboxOptions): Promise<Sandbox> {
+  static async get(id: string, options: SandboxOptions = {}): Promise<Sandbox> {
     const apiUrl = Sandbox.resolveApiUrl(options);
+    const authToken = Sandbox.resolveAuthToken(options);
 
     const res = await dntShim.fetch(`${apiUrl}/sandbox-sessions/${id}`, {
-      headers: { Authorization: `Bearer ${options.authToken}` },
+      headers: { Authorization: `Bearer ${authToken}` },
     });
 
     if (!res.ok) {
-      throw new Error(`Failed to get sandbox: ${res.status} ${await res.text()}`);
+      throw REQUEST_ERROR.create({
+        detail: `Failed to get sandbox: ${res.status} ${await res.text()}`,
+      });
     }
 
     const { endpoint } = await res.json();
-    return new Sandbox(endpoint, id, options.authToken, apiUrl);
+    return new Sandbox(endpoint, id, authToken, apiUrl);
   }
 
   private static async waitForReady(
@@ -99,6 +126,7 @@ export class Sandbox {
   ): Promise<void> {
     const start = Date.now();
     while (Date.now() - start < maxWaitMs) {
+      // no cleanup needed: one-shot
       await new Promise((r) => dntShim.setTimeout(r, pollIntervalMs));
 
       const res = await dntShim.fetch(`${apiUrl}/sandbox-sessions/${id}`, {
@@ -109,11 +137,13 @@ export class Sandbox {
         const data = await res.json();
         if (data.status === "running") return;
         if (data.status === "error" || data.status === "deleting") {
-          throw new Error(`Sandbox failed to start: status=${data.status}`);
+          throw INITIALIZATION_ERROR.create({
+            detail: `Sandbox failed to start: status=${data.status}`,
+          });
         }
       }
     }
-    throw new Error("Sandbox did not become ready within timeout");
+    throw TIMEOUT_ERROR.create({ detail: "Sandbox did not become ready within timeout" });
   }
 
   /** Execute a bash command in the sandbox and return buffered result. */
@@ -151,10 +181,13 @@ export class Sandbox {
     });
 
     if (!res.ok) {
-      throw new Error(`Exec failed: ${res.status} ${await res.text()}`);
+      throw REQUEST_ERROR.create({ detail: `Exec failed: ${res.status} ${await res.text()}` });
     }
 
-    const reader = res.body!.getReader();
+    if (!res.body) {
+      throw new Error("Exec response has no body");
+    }
+    const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
 
@@ -188,7 +221,7 @@ export class Sandbox {
     );
 
     if (!res.ok) {
-      throw new Error(`Read file failed: ${res.status} ${await res.text()}`);
+      throw REQUEST_ERROR.create({ detail: `Read file failed: ${res.status} ${await res.text()}` });
     }
 
     return res.text();
@@ -208,7 +241,9 @@ export class Sandbox {
     });
 
     if (!res.ok) {
-      throw new Error(`Write files failed: ${res.status} ${await res.text()}`);
+      throw REQUEST_ERROR.create({
+        detail: `Write files failed: ${res.status} ${await res.text()}`,
+      });
     }
   }
 

package/src/src/security/client/html-sanitizer.ts

@@ -10,23 +10,10 @@ import * as dntShim from "../../../_dnt.shims.js";
 
 
 import { escapeHtml } from "../../html/html-escape.js";
+import { SECURITY_VIOLATION } from "../../errors/index.js";
 
 export { escapeHtml };
 
-/**
- * Create text node safely (alternative to innerHTML for simple text).
- */
-export function createSafeTextNode(text: string): Text {
-  return document.createTextNode(text);
-}
-
-/**
- * Set text content safely (never interprets HTML).
- */
-export function setSafeTextContent(element: HTMLElement, text: string): void {
-  element.textContent = text;
-}
-
 /**
  * Patterns that RSC should never generate.
  * These indicate potential server compromise or misconfiguration.
@@ -53,7 +40,7 @@ function isDevMode(): boolean {
   return g.__VERYFRONT_DEV__ === true || g.Deno?.env?.get?.("VERYFRONT_ENV") === "development";
 }
 
-export interface ValidateTrustedHtmlOptions {
+interface ValidateTrustedHtmlOptions {
   /** Throw on suspicious patterns even in dev mode */
   strict?: boolean;
   /** Log warnings for suspicious patterns */
@@ -82,7 +69,9 @@ export function validateTrustedHtml(
     if (!pattern.test(html)) continue;
 
     if (warn) console.warn(`[Security] Suspicious ${name} detected in server HTML`);
-    if (strict || !isDevMode()) throw new Error(`Potentially unsafe HTML: ${name} detected`);
+    if (strict || !isDevMode()) {
+      throw SECURITY_VIOLATION.create({ detail: `Potentially unsafe HTML: ${name} detected` });
+    }
   }
 
   return html;

package/src/src/security/csrf/helpers.ts

@@ -80,8 +80,8 @@ export function validateCsrf(
   let cookieToken: string | undefined;
   try {
     cookieToken = parseCookiesFromHeaders(req.headers)[cookieName];
-  } catch {
-    // Malformed cookie (e.g. bad percent-encoding) → treat as missing
+  } catch (_) {
+    /* expected: malformed cookie (e.g. bad percent-encoding) → treat as missing */
     return false;
   }
   if (!cookieToken) return false;
@@ -123,8 +123,8 @@ export function applyCsrfCookie(
   let cookies: Record<string, string>;
   try {
     cookies = parseCookiesFromHeaders(req.headers);
-  } catch {
-    // Malformed cookie header — issue a fresh token
+  } catch (_) {
+    /* expected: malformed cookie header — issue a fresh token */
     cookies = {};
   }
   if (cookies[cookieName]) return;

package/src/src/security/http/auth.ts

@@ -15,8 +15,8 @@ function encodeBase64(value: string): string {
   if (typeof globalThis.btoa === "function") {
     try {
       return globalThis.btoa(value);
-    } catch {
-      // Fallback for non-Latin1 strings
+    } catch (_) {
+      /* expected: non-Latin1 string — fall back to TextEncoder */
       const bytes = new TextEncoder().encode(value);
       let binary = "";
       for (const byte of bytes) binary += String.fromCharCode(byte);
@@ -37,7 +37,7 @@ function encodeBase64(value: string): string {
 }
 
 function sanitizeRealm(realm: unknown): string {
-  // deno-lint-ignore no-control-regex
+  // deno-lint-ignore no-control-regex -- intentional: strips control chars and special chars from HTTP realm header
   return String(realm).replace(/[\x00-\x1f\x7f"\\]/g, "");
 }
 

package/src/src/security/http/base-handler.ts

@@ -124,8 +124,8 @@ export abstract class BaseHandler implements Handler {
     if (typeof fsWrapper.setRequestBranch === "function") {
       try {
         fsWrapper.setRequestBranch(ctx.parsedDomain?.branch ?? null);
-      } catch {
-        // Ignore - multi-project mode uses runWithContext for branch context
+      } catch (_) {
+        /* expected: multi-project mode uses runWithContext for branch context */
       }
     }
 

package/src/src/security/http/middleware/config-loader.ts

@@ -51,7 +51,8 @@ export function loadSecurityConfig(
         }
 
         return securityConfig;
-      } catch {
+      } catch (error) {
+        serverLogger.debug("Failed to load security config", { error });
         return null;
       }
     },

package/src/src/security/http/response/fluent-methods.ts

@@ -36,12 +36,16 @@ export function withCORS<T extends FluentMethodsContext>(
 }
 
 /** Apply CORS headers asynchronously */
-export function withCORSAsync<T extends FluentMethodsContext>(this: T, req: dntShim.Request): Promise<T> {
-  return applyCORSHeaders({
+export async function withCORSAsync<T extends FluentMethodsContext>(
+  this: T,
+  req: dntShim.Request,
+): Promise<T> {
+  await applyCORSHeaders({
     request: req,
     headers: this.headers,
     config: this.securityConfig?.cors,
-  }).then((): T => this);
+  });
+  return this;
 }
 
 /** Apply security headers (CSP, COOP, CORP, COEP) and optionally set CSRF cookie */

package/src/src/security/http/response/security-handler.ts

@@ -3,8 +3,14 @@ import type { RuntimeAdapter } from "../../../platform/adapters/base.js";
 import { recordSecurityHeaders } from "../../../observability/index.js";
 import type { SecurityConfig } from "./types.js";
 
+/** HSTS max-age default: 1 year in seconds */
+const HSTS_MAX_AGE_SECONDS = 31_536_000;
+
+/** Number of random bytes used to generate CSP nonces */
+const NONCE_BYTE_LENGTH = 16;
+
 export function generateNonce(): string {
-  const array = new Uint8Array(16);
+  const array = new Uint8Array(NONCE_BYTE_LENGTH);
   dntShim.crypto.getRandomValues(array);
   return btoa(String.fromCharCode(...array));
 }
@@ -83,7 +89,7 @@ export function applySecurityHeaders(
   if (csp) headers.set("Content-Security-Policy", csp);
 
   if (!isDev) {
-    const hstsMaxAge = config?.hsts?.maxAge ?? 31536000;
+    const hstsMaxAge = config?.hsts?.maxAge ?? HSTS_MAX_AGE_SECONDS;
     const hstsIncludeSubDomains = config?.hsts?.includeSubDomains ?? true;
     const hstsPreload = config?.hsts?.preload ?? false;
 

package/src/src/security/path-validation/canonical.ts

@@ -22,7 +22,8 @@ export async function getCanonicalPath(
   try {
     const stat = await adapter.fs.stat(path);
     return { path: resolvedPath, isSymlink: stat.isSymlink };
-  } catch {
+  } catch (_) {
+    /* expected: file may not exist when checking symlink status */
     return { path: resolvedPath, isSymlink: false };
   }
 }

package/src/src/security/path-validation/index.ts

@@ -108,7 +108,8 @@ export async function validatePath(
   if (checkExists && adapter) {
     try {
       await adapter.fs.stat(canonicalPath);
-    } catch {
+    } catch (_) {
+      /* expected: file does not exist at canonicalPath */
       return {
         valid: false,
         error: `File not found: ${canonicalPath}`,

package/src/src/security/path-validation/rules.ts

@@ -16,8 +16,7 @@ import { PathValidationError, type ValidationResult } from "./types.js";
  * Validate path for security issues (basic checks)
  */
 export function validatePathBasics(path: string): ValidationResult {
-  // deno-lint-ignore no-control-regex
-  if (path.includes("\0") || /\x00/.test(path)) {
+  if (path.includes("\0")) {
     return {
       valid: false,
       error: "Path contains null bytes",

package/src/src/security/secure-fs.ts

@@ -15,6 +15,7 @@ import {
 } from "./path-validation.js";
 import { withSpan } from "../observability/tracing/otlp-setup.js";
 import { SECURITY_VIOLATION } from "../errors/error-registry.js";
+import { getHostEnv } from "../platform/compat/process.js";
 
 const logger = baseLogger.component("secure-fs");
 
@@ -45,7 +46,7 @@ export interface SecurityEvent {
   timestamp: Date;
 }
 
-export interface ContextOptions {
+interface ContextOptions {
   allowedImportDirs?: string[];
 }
 
@@ -275,13 +276,18 @@ export class SecureFs {
     }
 
     const pathArg: string | string[] = validatedPaths.length === 1
-      ? validatedPaths[0]!
+      ? validatedPaths[0] ?? ""
       : validatedPaths;
 
     return this.config.adapter.fs.watch(pathArg, options);
   }
 
   getUnsafeAdapter(): RuntimeAdapter {
+    if (getHostEnv("NODE_ENV") === "production") {
+      throw SECURITY_VIOLATION.create({
+        detail: "getUnsafeAdapter() is not allowed in production",
+      });
+    }
     logger.warn("Using unsafe adapter - security checks bypassed!");
     return this.config.adapter;
   }

package/src/src/server/bootstrap.ts

@@ -7,11 +7,12 @@ import {
   refreshEnvironmentConfig,
 } from "../config/environment-config.js";
 import { getErrorMessage } from "../errors/veryfront-error.js";
+import { INVALID_ARGUMENT } from "../errors/index.js";
 import { enhanceAdapterWithFS } from "../platform/adapters/fs/integration.js";
 import { isExtendedFSAdapter } from "../platform/adapters/fs/wrapper.js";
 import { getEnv } from "../platform/compat/process.js";
 import { initializeEsbuild } from "../platform/compat/esbuild.js";
-import { logger, refreshLoggerConfig } from "../utils/index.js";
+import { logger } from "../utils/index.js";
 import { isDebugEnabled } from "../utils/constants/env.js";
 import {
   getEnvSource,
@@ -59,7 +60,6 @@ async function ensureEnvLoaded(projectDir: string, adapter: RuntimeAdapter): Pro
         debug: isDebugEnabled(adapter.env),
       });
       refreshEnvironmentConfig();
-      refreshLoggerConfig();
     } catch (error) {
       bootstrapLog.warn("Failed to load .env files", {
         error: getErrorMessage(error),
@@ -264,9 +264,9 @@ function validateProductionEnvironment(_adapter: RuntimeAdapter): void {
         "[Bootstrap:Prod] CRITICAL: NODE_ENV is not set in proxy mode. " +
           "Set NODE_ENV=production in your pod configuration.",
       );
-      throw new Error(
-        "NODE_ENV must be set to 'production' when running in proxy mode (PROXY_MODE=1)",
-      );
+      throw INVALID_ARGUMENT.create({
+        detail: "NODE_ENV must be set to 'production' when running in proxy mode (PROXY_MODE=1)",
+      });
     }
 
     if (nodeEnv !== "production") {

package/src/src/server/build-app-route-renderer.ts

@@ -16,7 +16,8 @@ async function fileExists(adapter: RuntimeAdapter, filePath: string): Promise<bo
   try {
     const st = await adapter.fs.stat(filePath);
     return st.isFile;
-  } catch {
+  } catch (_) {
+    /* expected: file may not exist */
     return false;
   }
 }
@@ -137,7 +138,7 @@ export async function renderAppRouteToHTML(args: {
     }
 
     if (document.readyState === 'loading') {
-      document.addEventListener('DOMContentLoaded', initializeApp);
+      document.addEventListener('DOMContentLoaded', initializeApp, { once: true });
     } else {
       initializeApp();
     }

package/src/src/server/build-routes.ts

@@ -117,8 +117,8 @@ async function walkAppSSG(
         segmentDirs: [...segDirs],
       });
       break;
-    } catch {
-      // continue
+    } catch (_) {
+      /* expected: file may not exist for this candidate */
     }
   }
 

package/src/src/server/build-service-worker.ts

@@ -134,7 +134,8 @@ async function handleRequest(request, strategy) {
         const response = await fetch(request);
         if (response.ok) cache.put(request, response.clone());
         return response;
-      } catch {
+      } catch (_) {
+        // expected: network unavailable, fall back to cache
         return cache.match(request);
       }
 

package/src/src/server/context/cache-invalidation.ts

@@ -10,13 +10,16 @@ import {
 } from "../../modules/react-loader/ssr-module-loader/index.js";
 import { cacheRegistry } from "../../cache/index.js";
 import { clearRendererCacheForProject } from "../../rendering/renderer.js";
-import { clearRouterDetectionCache } from "../../rendering/router-detection.js";
+import {
+  clearRouterDetectionCache,
+  clearRouterDetectionCacheForProject,
+} from "../../rendering/router-detection.js";
 import { clearSnippetCacheForProject } from "../../rendering/snippet-renderer.js";
 import { resetApiHandlerForProject } from "../handlers/request/api/pages-api-handler.js";
 
 const logger = serverLogger.component("cache-invalidation");
 
-export interface InvalidationOptions {
+interface InvalidationOptions {
   /** Environment scope: only invalidate caches for this environment */
   environment?: "production" | "preview";
   /** Branch ID for preview mode scoping */
@@ -72,8 +75,12 @@ export async function invalidateProjectCaches(
     clearSSRModuleCache();
   }
 
-  logger.debug("Clearing router detection cache", { projectSlug });
-  clearRouterDetectionCache();
+  logger.debug("Clearing router detection cache", { projectSlug, projectId });
+  if (projectId) {
+    clearRouterDetectionCacheForProject(projectId);
+  } else {
+    clearRouterDetectionCache();
+  }
 
   if (!hasRealProjectSlug) {
     logger.error(

package/src/src/server/context/enriched-context.ts

@@ -2,11 +2,12 @@ import type { RuntimeAdapter } from "../../platform/adapters/base.js";
 import type { VeryfrontConfig } from "../../config/index.js";
 import type { HandlerContext, ParsedDomain } from "../../types/index.js";
 import { buildRenderCachePrefix } from "../../cache/keys.js";
+import { INVALID_ARGUMENT } from "../../errors/index.js";
 
 export type Environment = "preview" | "production";
-export type RenderMode = "development" | "production";
+type RenderMode = "development" | "production";
 
-export interface ProjectData {
+interface ProjectData {
   id: string;
   slug: string;
   name?: string;
@@ -43,7 +44,7 @@ export interface EnrichedContext {
   createdAt: number;
 }
 
-export interface BuildEnrichedContextOptions {
+interface BuildEnrichedContextOptions {
   projectId: string;
   projectSlug: string;
   projectDir: string;
@@ -67,7 +68,7 @@ export interface BuildEnrichedContextOptions {
 
 export function buildEnrichedContext(options: BuildEnrichedContextOptions): EnrichedContext {
   if (!options.contentSourceId) {
-    throw new Error(`Missing contentSourceId for ${options.projectSlug}`);
+    throw INVALID_ARGUMENT.create({ detail: `Missing contentSourceId for ${options.projectSlug}` });
   }
 
   const releaseKey = options.environment === "production"

package/src/src/server/dev-server/error-overlay/html-template.ts

@@ -1,6 +1,15 @@
 import { type ErrorInfo, formatErrorType } from "./error-formatter.js";
 import { escapeHtml } from "../../../html/html-escape.js";
 
+/** Base delay multiplied by attempt count for WebSocket reconnection */
+const WS_RECONNECT_BASE_DELAY_MS = 1_000;
+
+/** Maximum delay between WebSocket reconnection attempts */
+const WS_RECONNECT_MAX_DELAY_MS = 5_000;
+
+/** Maximum number of WebSocket reconnection attempts before giving up */
+const WS_MAX_RECONNECT_ATTEMPTS = 10;
+
 export function generateRuntimeScript(): string {
   return `
     // Veryfront Error Overlay Runtime
@@ -279,7 +288,7 @@ export function generateErrorHTML(errorInfo: ErrorInfo, suggestion?: string): st
       const wsUrl = protocol + '//' + window.location.host + '/_ws';
       let ws = null;
       let reconnectAttempts = 0;
-      const maxReconnectAttempts = 10;
+      const maxReconnectAttempts = ${WS_MAX_RECONNECT_ATTEMPTS};
 
       function connect() {
         if (reconnectAttempts >= maxReconnectAttempts) return;
@@ -295,7 +304,7 @@ export function generateErrorHTML(errorInfo: ErrorInfo, suggestion?: string): st
         };
         ws.onclose = () => {
           reconnectAttempts++;
-          setTimeout(connect, Math.min(1000 * reconnectAttempts, 5000));
+          setTimeout(connect, Math.min(${WS_RECONNECT_BASE_DELAY_MS} * reconnectAttempts, ${WS_RECONNECT_MAX_DELAY_MS}));
         };
       }
       connect();

package/src/src/server/dev-server/file-watch-setup.ts

@@ -32,6 +32,13 @@ const IGNORED_PATH_PATTERNS = [
   ".veryfront\\",
 ];
 
+/**
+ * Project-root directory names that contain runtime data (not source code)
+ * and should be excluded from HMR. Matched by first path segment relative
+ * to projectDir to avoid false positives (e.g. "src/data/" is fine).
+ */
+const IGNORED_RUNTIME_DIRS = new Set(["data"]);
+
 /**
  * Check if a path should be ignored for HMR purposes.
  */
@@ -126,8 +133,10 @@ export class FileWatchSetup {
         if (signal.aborted) break;
 
         try {
-          // Filter out paths that shouldn't trigger HMR (cache, node_modules, etc.)
-          const relevantPaths = paths.filter((p) => !shouldIgnorePath(p));
+          // Filter out paths that shouldn't trigger HMR (cache, node_modules, runtime data, etc.)
+          const relevantPaths = paths.filter((p) =>
+            !shouldIgnorePath(p) && !this.isRuntimeDataPath(p)
+          );
           if (relevantPaths.length === 0) continue;
 
           if (this.optimizedWatcher) {
@@ -175,6 +184,16 @@ export class FileWatchSetup {
     return this.aiDirs.has(firstSegment);
   }
 
+  /**
+   * Check if a path is inside a runtime data directory (data/, etc.)
+   * that contains generated content (embedding indices) rather than source code.
+   */
+  private isRuntimeDataPath(fullPath: string): boolean {
+    const rel = relative(this.projectDir, fullPath);
+    const firstSegment = rel.split(sep)[0] ?? "";
+    return IGNORED_RUNTIME_DIRS.has(firstSegment);
+  }
+
   /** FNV-1a hash for fast content comparison */
   private hashContent(content: string): number {
     let h = 2166136261;
@@ -195,8 +214,8 @@ export class FileWatchSetup {
         if (this.contentHashes.get(path) === hash) continue;
         this.contentHashes.set(path, hash);
         changed.push(path);
-      } catch {
-        // File deleted or unreadable — treat as changed
+      } catch (_) {
+        /* expected: file may be deleted or unreadable — treat as changed */
         this.contentHashes.delete(path);
         changed.push(path);
       }