fix(server): idempotent fileRead({ifExists: true}) for race-prone batch reads

Two pathologies were silently logging 404s in DevTools and routing through
installFetchProxy's retry path on every space switch and config-load:

1. Batch readers in spaces/storage.js (readSpace, parseWidgetFiles batch,
   listSpaces) walk the path index and then read all matched files. A
   widget or manifest can be deleted between the index walk and the read
   (concurrent space deletion, file_explorer rename, watchdog catching
   up), failing the entire batch.

2. Optional config readers across the codebase load files like
   ~/conf/dashboard.yaml, ~/conf/onscreen-agent.yaml,
   ~/conf/personality.system.include.md, ~/user.yaml. On a fresh user
   account these never existed, so the load wraps the call in
   try/catch + isMissingFileError and treats 404 as "use defaults". The
   404 is suppressed in JS but still logged by the browser before
   JavaScript can intercept it.

This PR adds an opt-in `ifExists: true` option to fileRead, mirroring the
shape of fileDelete({ifExists: true}) (PR #35). Server returns 200; missing
paths appear under `skipped[]`; the singular form returns
{content: null, encoding: null, path: null, skipped: [requested]}. Strict
semantics remain the default for user-initiated reads and known-must-exist
paths so a real "this resource is gone" diagnostic still surfaces.

Server side:
- normalizeReadRequests reads options.ifExists; missing paths go into
  skipped[] instead of throwing 404. Other resolution failures (empty
  path, directory-instead-of-file, public-only, permission) still throw.
- readAppFiles surfaces skipped on the result envelope when non-empty
  and additionally catches ENOENT from fs.readFileSync when ifExists is
  set, closing the race where the path index says the file is there
  but it has been removed externally since the last scan.
- readAppFile keeps its singular contract; returns content: null /
  encoding: null / path: null when the only path was skipped.
- file_read endpoint reads ifExists from POST body or GET query
  (?ifExists=1) so the bare-path GET form keeps working without
  forcing every idempotent read into POST.

Client side:
- createFileReadRequest accepts a third positional argument for the
  bare-path/array forms and an ifExists field on the object forms.
  Strict bodies/queries byte-identical to today.
- fileRead branches: idempotent reads bypass the file-read batching
  queue and call directly into call("file_read", ...). Mixing strict
  and idempotent modes in one batch would change the strict caller's
  behaviour, so the bypass keeps each idempotent call's semantic
  isolated. The queue's batching benefit is preserved for the strict
  default.

Migrated callers:

Pathology 1 (race-prone batch reads in spaces/storage.js):
- readSpace(...) — manifest + widgets batch
- parseWidgetFiles(...) batch — widget batch
- listSpaces(...) bulk — manifest+widgets across all spaces

Pathology 2 (optional config readers; previously try/catch + 404):
- agent/storage.js loadAgentPersonality
- user/storage.js readUserConfig
- dashboard_welcome/dashboard-prefs.js loadDashboardPrefs
- onscreen_agent/storage.js loadOnscreenAgentConfig + loadOnscreenAgentHistory
- admin/views/agent/storage.js loadAdminChatConfig + loadAdminChatHistory
- login_hooks/login-hooks.js hasFirstLoginMarker (fileRead fallback path)
- panels/panel-index.js listPanels batch

Each of these had its own copy of the isMissingFileError(...) helper for
the same regex. Where the helper has no remaining users in a file, this
PR removes it; module_remove and other strict callers keep their copies.

server/api/AGENTS.md documents the new option alongside the existing
file_write operation-modes documentation.

Strict callers untouched: readWidgetFile, readManifestFile's duplicateSpace
caller, all single-file reads paired with a known-existing target.

Author: Syring, Nikolas

app/L0/_all/mod/_core/admin/views/agent/storage.js

@@ -37,11 +37,6 @@ function getRuntime() {
   return runtime;
 }
 
-function isMissingFileError(error) {
-  const message = String(error?.message || "");
-  return /\bstatus 404\b/u.test(message) || /File not found\./u.test(message);
-}
-
 function isSingleUserAppRuntime(runtime) {
   return Boolean(runtime?.config?.get?.("SINGLE_USER_APP", false));
 }
@@ -198,16 +193,20 @@ async function buildStoredConfigPayload(runtime, { settings, systemPrompt }) {
 export async function loadAdminChatConfig() {
   const runtime = getRuntime();
 
+  // Idempotent read: a fresh user has no `~/conf/admin-chat.yaml` yet.
+  // ifExists returns content: null instead of throwing 404.
+  let result;
   try {
-    const result = await runtime.api.fileRead(config.ADMIN_CHAT_CONFIG_PATH);
-    return normalizeStoredConfig(runtime, runtime.utils.yaml.parse(String(result?.content || "")));
+    result = await runtime.api.fileRead(config.ADMIN_CHAT_CONFIG_PATH, "utf8", { ifExists: true });
   } catch (error) {
-    if (isMissingFileError(error)) {
-      return createDefaultConfig();
-    }
-
     throw new Error(`Unable to load admin chat config: ${error.message}`);
   }
+
+  if (typeof result?.content !== "string") {
+    return createDefaultConfig();
+  }
+
+  return normalizeStoredConfig(runtime, runtime.utils.yaml.parse(result.content));
 }
 
 export async function saveAdminChatConfig(nextConfig) {
@@ -229,20 +228,27 @@ export async function saveAdminChatConfig(nextConfig) {
 export async function loadAdminChatHistory() {
   const runtime = getRuntime();
 
+  // Idempotent read: history file may not exist on first run.
+  let result;
   try {
-    const result = await runtime.api.fileRead(config.ADMIN_CHAT_HISTORY_PATH);
-    const parsed = JSON.parse(String(result?.content || "[]"));
-    return Array.isArray(parsed) ? parsed : [];
+    result = await runtime.api.fileRead(config.ADMIN_CHAT_HISTORY_PATH, "utf8", { ifExists: true });
   } catch (error) {
-    if (isMissingFileError(error)) {
-      return [];
-    }
+    throw new Error(`Unable to load admin chat history: ${error.message}`);
+  }
+
+  if (typeof result?.content !== "string") {
+    return [];
+  }
 
+  try {
+    const parsed = JSON.parse(result.content || "[]");
+    return Array.isArray(parsed) ? parsed : [];
+  } catch (error) {
     if (error instanceof SyntaxError) {
       throw new Error("Unable to load admin chat history: invalid JSON.");
     }
 
-    throw new Error(`Unable to load admin chat history: ${error.message}`);
+    throw error;
   }
 }
 

app/L0/_all/mod/_core/agent/storage.js

@@ -18,22 +18,15 @@ function getRuntime() {
   return runtime;
 }
 
-function isMissingFileError(error) {
-  const message = String(error?.message || "");
-  return /\bstatus 404\b/u.test(message) || /File not found\./u.test(message) || /Path not found\./u.test(message);
-}
-
 export async function loadAgentPersonality() {
   const runtime = getRuntime();
 
+  // Idempotent read: this config is optional. Use ifExists so a missing
+  // file returns content: null instead of throwing 404.
   try {
-    const result = await runtime.api.fileRead(AGENT_PERSONALITY_PATH);
+    const result = await runtime.api.fileRead(AGENT_PERSONALITY_PATH, "utf8", { ifExists: true });
     return String(result?.content || "");
   } catch (error) {
-    if (isMissingFileError(error)) {
-      return "";
-    }
-
     throw new Error(`Unable to load agent personality: ${error.message}`);
   }
 }

app/L0/_all/mod/_core/dashboard_welcome/dashboard-prefs.js

@@ -29,11 +29,6 @@ function getRuntime() {
   return runtime;
 }
 
-function isMissingFileError(error) {
-  const message = String(error?.message || "");
-  return /\bstatus 404\b/u.test(message) || /File not found\./u.test(message) || /Path not found\./u.test(message);
-}
-
 function parseStoredBoolean(value) {
   if (value === true || value === false) {
     return value;
@@ -92,14 +87,13 @@ export function subscribeDashboardWelcomeHiddenChange(callback) {
 export async function loadDashboardPrefs() {
   const runtime = getRuntime();
 
+  // Idempotent read: a fresh user has no `~/conf/dashboard.yaml` yet. Use
+  // ifExists so the missing file returns content: null instead of throwing
+  // 404 (and triggering DevTools console noise on every space switch).
   try {
-    const result = await runtime.api.fileRead(DASHBOARD_CONFIG_PATH);
+    const result = await runtime.api.fileRead(DASHBOARD_CONFIG_PATH, "utf8", { ifExists: true });
     return normalizeDashboardPrefs(runtime.utils.yaml.parse(String(result?.content || "")));
   } catch (error) {
-    if (isMissingFileError(error)) {
-      return normalizeDashboardPrefs({});
-    }
-
     throw new Error(`Unable to load dashboard settings: ${error.message}`);
   }
 }

app/L0/_all/mod/_core/framework/js/api-client.js

@@ -350,11 +350,23 @@ function serializeStableValue(value) {
     .join(",")}}`;
 }
 
-function createFileReadRequest(pathOrFiles, encoding) {
+function createFileReadRequest(pathOrFiles, encoding, options) {
+  // `ifExists: true` opts into idempotent read semantics: missing paths
+  // resolve to a 200 response with `content: null` (singular form) or
+  // listed under `skipped` (batch form) instead of throwing 404. The
+  // option arrives either through the third positional argument
+  // (bare-path / array forms) or as an `ifExists` field on the input
+  // object (object forms); the input object wins when both are set.
+  const optionsObject = isPlainObject(options) ? options : {};
+  const ifExistsFlag = optionsObject.ifExists === true;
+  const ifExistsBody = ifExistsFlag ? { ifExists: true } : {};
+  const ifExistsQuery = ifExistsFlag ? { ifExists: "1" } : {};
+
   if (Array.isArray(pathOrFiles)) {
     return {
       method: "POST",
       body: {
+        ...ifExistsBody,
         encoding,
         files: pathOrFiles
       }
@@ -365,6 +377,8 @@ function createFileReadRequest(pathOrFiles, encoding) {
     return {
       method: "POST",
       body: {
+        ...ifExistsBody,
+        ...(typeof pathOrFiles.ifExists === "boolean" ? { ifExists: pathOrFiles.ifExists } : {}),
         encoding: pathOrFiles.encoding ?? encoding,
         files: pathOrFiles.files
       }
@@ -375,6 +389,8 @@ function createFileReadRequest(pathOrFiles, encoding) {
     return {
       method: "POST",
       body: {
+        ...ifExistsBody,
+        ...(typeof pathOrFiles.ifExists === "boolean" ? { ifExists: pathOrFiles.ifExists } : {}),
         encoding: pathOrFiles.encoding ?? encoding,
         path: pathOrFiles.path
       }
@@ -384,6 +400,7 @@ function createFileReadRequest(pathOrFiles, encoding) {
   return {
     method: "GET",
     query: {
+      ...ifExistsQuery,
       encoding,
       path: pathOrFiles
     }
@@ -1000,11 +1017,33 @@ export function createApiClient(options = {}) {
    * `~` or `~/...` shorthand for the current user's `L2/<username>/...` path.
    * It also accepts composed batch input through a `files` array.
    *
+   * Pass `{ ifExists: true }` (either on the input object for the
+   * `{path}` / `{files}` forms or as a third positional argument for the
+   * bare-path / array forms) to opt into idempotent semantics: paths that
+   * do not exist return `200`. The singular form returns
+   * `{ content: null, encoding: null, path: null, skipped: [requested] }`;
+   * the batch form returns the read files plus a `skipped[]` field for
+   * any missing entries. Without `ifExists` the call stays strict so
+   * callers that need authoritative 404 keep their existing behaviour.
+   *
+   * Idempotent reads bypass the file-read batching queue so the option
+   * is applied per-call and missing paths cannot poison a shared batch.
+   *
    * @param {string | FileReadInput[] | FileReadBatchOptions | FileReadInput} pathOrFiles
    * @param {string} [encoding]
+   * @param {{ ifExists?: boolean }} [options]
    * @returns {Promise<FileApiResult | FileBatchApiResult>}
    */
-  async function fileRead(pathOrFiles, encoding = "utf8") {
+  async function fileRead(pathOrFiles, encoding = "utf8", options) {
+    const optionsObject = isPlainObject(options) ? options : {};
+    const inputIfExists =
+      isPlainObject(pathOrFiles) && typeof pathOrFiles.ifExists === "boolean" ? pathOrFiles.ifExists : null;
+    const ifExistsFlag = inputIfExists === true || optionsObject.ifExists === true;
+
+    if (ifExistsFlag) {
+      return call("file_read", createFileReadRequest(pathOrFiles, encoding, { ifExists: true }));
+    }
+
     return queueFileRead(pathOrFiles, encoding);
   }
 

app/L0/_all/mod/_core/login_hooks/login-hooks.js

@@ -100,14 +100,12 @@ async function hasFirstLoginMarker(runtime, markerPath) {
     }
   }
 
+  // fileRead-fallback when fileInfo is not available. Idempotent read so a
+  // missing marker resolves cleanly without console-spamming a 404.
   try {
-    await runtime.api.fileRead(markerPath);
-    return true;
+    const result = await runtime.api.fileRead(markerPath, "utf8", { ifExists: true });
+    return typeof result?.content === "string";
   } catch (error) {
-    if (isMissingFileError(error)) {
-      return false;
-    }
-
     throw error;
   }
 }

app/L0/_all/mod/_core/onscreen_agent/storage.js

@@ -124,11 +124,6 @@ function getRuntime() {
   return runtime;
 }
 
-function isMissingFileError(error) {
-  const message = String(error?.message || "");
-  return /\bstatus 404\b/u.test(message) || /File not found\./u.test(message);
-}
-
 function isSingleUserAppRuntime(runtime) {
   return Boolean(runtime?.config?.get?.("SINGLE_USER_APP", false));
 }
@@ -388,52 +383,58 @@ export async function loadOnscreenAgentConfig() {
   const runtime = getRuntime();
   const uiStateOwner = await getUiStateOwner(runtime);
 
+  // Idempotent read: a fresh user has no `~/conf/onscreen-agent.yaml` yet.
+  // Use ifExists so the missing file returns content: null instead of
+  // throwing 404 on every space switch and console-spamming the user.
+  let result;
   try {
-    const result = await runtime.api.fileRead(config.ONSCREEN_AGENT_CONFIG_PATH);
-    const normalizedConfig = await normalizeStoredConfig(
-      runtime,
-      runtime.utils.yaml.parse(String(result?.content || ""))
-    );
+    result = await runtime.api.fileRead(config.ONSCREEN_AGENT_CONFIG_PATH, "utf8", { ifExists: true });
+  } catch (error) {
+    throw new Error(`Unable to load onscreen agent config: ${error.message}`);
+  }
+
+  if (typeof result?.content !== "string") {
+    // Missing config: fall through to first-run defaults with optional UI state replay.
     const storedUiState =
-      loadUiStateFromStorageArea("sessionStorage", { owner: uiStateOwner }) ||
-      loadUiStateFromStorageArea("localStorage", { owner: uiStateOwner }) ||
-      normalizeStoredUiState(normalizedConfig);
+      loadUiStateFromStorageArea("sessionStorage", { allowUnowned: false, owner: uiStateOwner }) ||
+      loadUiStateFromStorageArea("localStorage", { allowUnowned: false, owner: uiStateOwner });
+    const defaultConfig = createDefaultConfig();
 
-    return {
-      settings: normalizedConfig.settings,
-      systemPrompt: normalizedConfig.systemPrompt,
-      ...storedUiState,
-      uiStateOwner,
-      shouldCenterInitialPosition: false
-    };
-  } catch (error) {
-    if (isMissingFileError(error)) {
-      const storedUiState =
-        loadUiStateFromStorageArea("sessionStorage", { allowUnowned: false, owner: uiStateOwner }) ||
-        loadUiStateFromStorageArea("localStorage", { allowUnowned: false, owner: uiStateOwner });
-      const defaultConfig = createDefaultConfig();
-
-      if (storedUiState) {
-        return {
-          settings: defaultConfig.settings,
-          systemPrompt: defaultConfig.systemPrompt,
-          ...storedUiState,
-          uiStateOwner,
-          shouldCenterInitialPosition: false
-        };
-      }
-
-      // A missing per-user config with no owner-tagged UI state means first-run defaults for this load.
+    if (storedUiState) {
       return {
-        ...defaultConfig,
-        ...createDefaultUiState(),
+        settings: defaultConfig.settings,
+        systemPrompt: defaultConfig.systemPrompt,
+        ...storedUiState,
         uiStateOwner,
-        shouldCenterInitialPosition: true
+        shouldCenterInitialPosition: false
       };
     }
 
-    throw new Error(`Unable to load onscreen agent config: ${error.message}`);
+    // A missing per-user config with no owner-tagged UI state means first-run defaults for this load.
+    return {
+      ...defaultConfig,
+      ...createDefaultUiState(),
+      uiStateOwner,
+      shouldCenterInitialPosition: true
+    };
   }
+
+  const normalizedConfig = await normalizeStoredConfig(
+    runtime,
+    runtime.utils.yaml.parse(result.content)
+  );
+  const storedUiState =
+    loadUiStateFromStorageArea("sessionStorage", { owner: uiStateOwner }) ||
+    loadUiStateFromStorageArea("localStorage", { owner: uiStateOwner }) ||
+    normalizeStoredUiState(normalizedConfig);
+
+  return {
+    settings: normalizedConfig.settings,
+    systemPrompt: normalizedConfig.systemPrompt,
+    ...storedUiState,
+    uiStateOwner,
+    shouldCenterInitialPosition: false
+  };
 }
 
 export async function saveOnscreenAgentConfig(nextConfig) {
@@ -460,20 +461,28 @@ export function saveOnscreenAgentUiState(nextState) {
 export async function loadOnscreenAgentHistory() {
   const runtime = getRuntime();
 
+  // Idempotent read: history file may not exist on first run. ifExists
+  // returns content: null instead of throwing 404.
+  let result;
   try {
-    const result = await runtime.api.fileRead(config.ONSCREEN_AGENT_HISTORY_PATH);
-    const parsed = JSON.parse(String(result?.content || "[]"));
-    return Array.isArray(parsed) ? parsed : [];
+    result = await runtime.api.fileRead(config.ONSCREEN_AGENT_HISTORY_PATH, "utf8", { ifExists: true });
   } catch (error) {
-    if (isMissingFileError(error)) {
-      return [];
-    }
+    throw new Error(`Unable to load onscreen agent history: ${error.message}`);
+  }
+
+  if (typeof result?.content !== "string") {
+    return [];
+  }
 
+  try {
+    const parsed = JSON.parse(result.content || "[]");
+    return Array.isArray(parsed) ? parsed : [];
+  } catch (error) {
     if (error instanceof SyntaxError) {
       throw new Error("Unable to load onscreen agent history: invalid JSON.");
     }
 
-    throw new Error(`Unable to load onscreen agent history: ${error.message}`);
+    throw error;
   }
 }
 

app/L0/_all/mod/_core/panels/panel-index.js

@@ -251,8 +251,14 @@ export async function listPanels() {
     return [];
   }
 
+  // Idempotent batch read: panel manifests can be removed by module_remove
+  // between the listing and this read. The panels parser keys files by
+  // path through a Map, so missing entries simply do not appear in the
+  // lookup — same shape we get from a 200 with `skipped`, just without
+  // the 404 console noise.
   const result = await runtime.api.fileRead({
-    files: manifestFiles.map((manifestFile) => manifestFile.filePath)
+    files: manifestFiles.map((manifestFile) => manifestFile.filePath),
+    ifExists: true
   });
   const files = Array.isArray(result?.files) ? result.files : [];
   const fileMap = new Map(