mulmoclaude 2.3.0 → 2.4.1

package/src/composables/usePubSub.ts

@@ -1,4 +1,6 @@
 import { io, type Socket } from "socket.io-client";
+import { getAuthToken } from "../utils/auth/authToken";
+import { authTokenStale, recoverAuthToken } from "../utils/auth/authTokenRecovery";
 
 interface PubSubMessage {
   channel: string;
@@ -35,6 +37,23 @@ function fireReconnectHandlers(): void {
   }
 }
 
+/** The server refused the handshake. The token is regenerated at every server
+ *  start, so this is what a restart looks like from a page that stayed open;
+ *  index.html carries the new token, and `auth` re-reads it on the next
+ *  CONNECT. socket.io does not retry a refusal on its own (#3433), so the
+ *  reconnect is explicit — and only with a token the server has not refused
+ *  yet, so a second refusal ends with the banner rather than a loop (#3438). */
+async function reconnectWithFreshToken(refusedSocket: Socket): Promise<void> {
+  const recovery = await recoverAuthToken();
+  // `maybeDisconnect` may have let go of this socket while index.html was fetched.
+  if (socket !== refusedSocket) return;
+  if (recovery === "installed") {
+    refusedSocket.connect();
+    return;
+  }
+  authTokenStale.value = true;
+}
+
 function connect(): Socket {
   if (socket) return socket;
 
@@ -42,9 +61,13 @@ function connect(): Socket {
     path: "/ws/pubsub",
     // Server refuses long-polling fallback, so fail fast here too if the WS upgrade doesn't go through.
     transports: ["websocket"],
+    // The same bearer token every `apiCall` attaches (#3433). A function, so
+    // each CONNECT re-reads it instead of re-sending the first value.
+    auth: (provide) => provide({ token: getAuthToken() }),
   });
 
   sock.on("connect", () => {
+    authTokenStale.value = false;
     resendSubscriptions(sock);
     if (hasConnectedOnce) {
       fireReconnectHandlers();
@@ -53,6 +76,15 @@ function connect(): Socket {
     }
   });
 
+  sock.on("connect_error", (err: Error) => {
+    // A transport failure leaves `active` true and socket.io retries it on its
+    // own. A refusal from the server middleware destroys the socket (`active`
+    // false) and nothing else will retry it.
+    if (sock.active) return;
+    console.error("[usePubSub] handshake refused by the server:", err.message);
+    void reconnectWithFreshToken(sock);
+  });
+
   sock.on("data", (msg: PubSubMessage) => {
     const cbs = listeners.get(msg.channel);
     if (cbs) {

package/src/config/systemFileDescriptors.ts

@@ -55,7 +55,7 @@ export const SYSTEM_FILE_DESCRIPTORS: readonly Entry[] = [
   {
     kind: "exact",
     path: "config/scheduler/overrides.json",
-    descriptor: { id: "schedulerOverrides", schemaRef: "server/utils/files/scheduler-io.ts", editPolicy: "agent-managed" },
+    descriptor: { id: "schedulerOverrides", schemaRef: "server/utils/files/scheduler-overrides-io.ts", editPolicy: "agent-managed" },
   },
   // ── data/ ──
   {

package/src/lang/de.ts

@@ -139,6 +139,11 @@ const deMessages = {
     body: "Ihr Telefon kann erst nach dem erneuten Verbinden an dieses Gerät senden.",
     reconnect: "Erneut verbinden",
   },
+  authTokenStale: {
+    title: "Diese Seite muss neu geladen werden",
+    body: "Der Server hat das Token dieser Seite abgelehnt, und ein neues konnte nicht abgerufen werden. Laden Sie die Seite neu, um fortzufahren.",
+    reload: "Neu laden",
+  },
   remoteHost: {
     title: "Remote-Host",
     online: "Remote-Host online",
@@ -607,8 +612,9 @@ const deMessages = {
         "Pro-Aufgabe Zeit-/Intervall-Überschreibungen über dem Systemzeitplan. Der Agent bearbeitet dies, wenn du den Zeitpunkt einer wiederkehrenden Aufgabe änderst.",
     },
     schedulerItems: {
-      title: "Scheduler-Item-Warteschlange",
-      summary: "Geplante Aufrufe, die zur Auslösung bereitstehen. Agent-verwaltet; nicht von Hand bearbeiten, ohne jedes Feld zu verstehen.",
+      title: "Alte Kalendereinträge",
+      summary:
+        "Einträge aus der entfernten Kalenderansicht. Die App zeigt sie nicht mehr an, und nichts führt sie nach Zeitplan aus; nur die alten /api/scheduler-Aktionen lesen und schreiben diese Datei noch. Geplante Aufgaben liegen in config/scheduler/tasks.json.",
     },
     wikiIndex: {
       title: "Wiki-Index",
@@ -630,9 +636,9 @@ const deMessages = {
         "Formatspezifikation, die der Agent liest, um Wiki-Seiten konsistent zu halten. Empfindlich — eine bestimmte Struktur wird erwartet; bevorzuge Agent-getriebene Bearbeitung.",
     },
     memory: {
-      title: "Memory",
+      title: "Memory (alte Datei)",
       summary:
-        "Destillierte Fakten über dich, immer als Kontext für neue Gespräche geladen. Der Journal-Extraktor hängt automatisch an; manuelle Bearbeitung ebenfalls möglich.",
+        "Das ältere Ein-Datei-Gedächtnis. Nur Arbeitsbereiche im älteren Format lesen es; aktuelle Arbeitsbereiche speichern Fakten als Themendateien unter conversations/memory/<type>/<topic>.md und ignorieren diese Datei, Änderungen hier wirken dort also nicht.",
     },
     summariesIndex: {
       title: "Zusammenfassungs-Index",

package/src/lang/en.ts

@@ -157,6 +157,11 @@ const enMessages = {
     body: "Your phone can't send to this device until you reconnect.",
     reconnect: "Reconnect",
   },
+  authTokenStale: {
+    title: "This page needs a reload",
+    body: "The server refused this page's token and a new one could not be fetched. Reload to continue.",
+    reload: "Reload",
+  },
   remoteHost: {
     title: "Remote host",
     online: "Remote host online",
@@ -624,8 +629,9 @@ const enMessages = {
         "Per-task time / interval overrides applied on top of the system schedule. The agent edits this when you ask to change a recurring task's timing.",
     },
     schedulerItems: {
-      title: "Scheduler items queue",
-      summary: "Active scheduled invocations ready to fire. Agent-managed; do not hand-edit unless you know exactly what each field means.",
+      title: "Legacy calendar items",
+      summary:
+        "Calendar items from the removed Calendar view. The app no longer shows them and nothing runs them on a schedule; only the legacy /api/scheduler actions still read and write this file. Scheduled tasks live in config/scheduler/tasks.json.",
     },
     wikiIndex: {
       title: "Wiki index",
@@ -644,9 +650,9 @@ const enMessages = {
       summary: "The format spec the agent reads to keep wiki pages consistent. Fragile — the agent expects a specific structure, so prefer agent-driven edits.",
     },
     memory: {
-      title: "Memory",
+      title: "Memory (legacy file)",
       summary:
-        "Distilled facts about you, always loaded as context for new conversations. The journal extractor appends here automatically; you can also hand-edit.",
+        "The older single-file memory. Only workspaces still on the older memory format read it; current workspaces keep facts as topic files under conversations/memory/<type>/<topic>.md and ignore this file, so editing it has no effect there.",
     },
     summariesIndex: {
       title: "Summaries index",

package/src/lang/es.ts

@@ -142,6 +142,11 @@ const esMessages = {
     body: "Tu teléfono no podrá enviar a este dispositivo hasta que vuelvas a conectarte.",
     reconnect: "Reconectar",
   },
+  authTokenStale: {
+    title: "Esta página necesita recargarse",
+    body: "El servidor rechazó el token de esta página y no se pudo obtener uno nuevo. Recarga para continuar.",
+    reload: "Recargar",
+  },
   remoteHost: {
     title: "Host remoto",
     online: "Host remoto en línea",
@@ -607,8 +612,9 @@ const esMessages = {
         "Sobrescrituras de hora / intervalo por tarea aplicadas sobre el horario del sistema. El agente las edita cuando pides cambiar la franja de una tarea recurrente.",
     },
     schedulerItems: {
-      title: "Cola de elementos del programador",
-      summary: "Invocaciones programadas listas para dispararse. Gestionado por el agente; no edites a mano salvo que entiendas cada campo.",
+      title: "Elementos de calendario antiguos",
+      summary:
+        "Elementos de la vista de Calendario eliminada. La app ya no los muestra y nada los ejecuta según una programación; solo las acciones antiguas de /api/scheduler siguen leyendo y escribiendo este archivo. Las tareas programadas están en config/scheduler/tasks.json.",
     },
     wikiIndex: {
       title: "Índice de la wiki",
@@ -628,9 +634,9 @@ const esMessages = {
         "Especificación de formato que el agente lee para mantener las páginas consistentes. Frágil — espera una estructura concreta; prefiere ediciones del agente.",
     },
     memory: {
-      title: "Memoria",
+      title: "Memoria (archivo antiguo)",
       summary:
-        "Hechos destilados sobre ti, cargados siempre como contexto en conversaciones nuevas. El extractor del journal añade automáticamente; también puedes editar a mano.",
+        "La memoria antigua de un solo archivo. Solo la leen los espacios de trabajo con el formato antiguo; los actuales guardan los hechos como archivos de tema en conversations/memory/<type>/<topic>.md e ignoran este archivo, así que editarlo no tiene efecto en ellos.",
     },
     summariesIndex: {
       title: "Índice de resúmenes",

package/src/lang/fr.ts

@@ -137,6 +137,11 @@ const frMessages = {
     body: "Votre téléphone ne pourra pas envoyer vers cet appareil tant que vous n'êtes pas reconnecté.",
     reconnect: "Se reconnecter",
   },
+  authTokenStale: {
+    title: "Cette page doit être rechargée",
+    body: "Le serveur a refusé le jeton de cette page et un nouveau n'a pas pu être récupéré. Rechargez pour continuer.",
+    reload: "Recharger",
+  },
   remoteHost: {
     title: "Hôte distant",
     online: "Hôte distant en ligne",
@@ -602,8 +607,9 @@ const frMessages = {
         "Surcharges horaires / d'intervalle par tâche appliquées au-dessus du planning système. L'agent édite ce fichier quand vous demandez à changer l'horaire d'une tâche récurrente.",
     },
     schedulerItems: {
-      title: "File d'éléments du planificateur",
-      summary: "Invocations planifiées prêtes à se déclencher. Géré par l'agent ; n'éditez pas à la main sans comprendre chaque champ.",
+      title: "Anciens éléments de calendrier",
+      summary:
+        "Éléments de la vue Calendrier supprimée. L'application ne les affiche plus et rien ne les exécute selon un planning ; seules les anciennes actions /api/scheduler lisent et écrivent encore ce fichier. Les tâches planifiées se trouvent dans config/scheduler/tasks.json.",
     },
     wikiIndex: {
       title: "Index du wiki",
@@ -623,9 +629,9 @@ const frMessages = {
         "Spécification de format que l'agent lit pour garder les pages du wiki cohérentes. Fragile — il attend une structure précise ; préférez les éditions via l'agent.",
     },
     memory: {
-      title: "Mémoire",
+      title: "Mémoire (ancien fichier)",
       summary:
-        "Faits distillés à votre sujet, toujours chargés comme contexte pour les nouvelles conversations. L'extracteur du journal y ajoute automatiquement ; vous pouvez aussi éditer à la main.",
+        "L'ancienne mémoire en un seul fichier. Seuls les espaces de travail encore à l'ancien format la lisent ; les espaces actuels stockent les faits dans des fichiers de sujet sous conversations/memory/<type>/<topic>.md et ignorent ce fichier, donc le modifier n'a pas d'effet pour eux.",
     },
     summariesIndex: {
       title: "Index des résumés",

package/src/lang/ja.ts

@@ -142,6 +142,11 @@ const jaMessages = {
     body: "再接続するまで、スマホからの送信はこの端末に届きません。",
     reconnect: "再接続",
   },
+  authTokenStale: {
+    title: "ページの再読み込みが必要です",
+    body: "サーバーがこのページのトークンを拒否し、新しいトークンを取得できませんでした。続けるには再読み込みしてください。",
+    reload: "再読み込み",
+  },
   remoteHost: {
     title: "リモートホスト",
     online: "リモートホスト: オンライン",
@@ -598,8 +603,9 @@ const jaMessages = {
       summary: "システム既定スケジュールに上書きするタスクごとの時刻 / 間隔の上書き。会話で「このタスクの時刻を変えて」と頼むとエージェントが書き換えます。",
     },
     schedulerItems: {
-      title: "スケジューラアイテムキュー",
-      summary: "発火待ちの予約済み実行キュー。エージェント管理 — 各フィールドの意味を理解していなければ手動編集しないでください。",
+      title: "旧カレンダー項目",
+      summary:
+        "削除済みのカレンダー画面の項目。アプリには表示されず、予定どおりに実行されることもありません。このファイルを読み書きするのは旧来の /api/scheduler の操作だけです。予定タスクは config/scheduler/tasks.json にあります。",
     },
     wikiIndex: {
       title: "Wiki インデックス",
@@ -618,8 +624,9 @@ const jaMessages = {
       summary: "Wiki ページの一貫性を保つためにエージェントが参照する書式仕様。壊れやすい — 特定の構造を期待するため、エージェント主導の編集を推奨します。",
     },
     memory: {
-      title: "メモリ",
-      summary: "新しい会話のコンテキストとして常に読み込まれる、あなたに関する蒸留された事実。journal の抽出器が自動追記し、手動編集も可能です。",
+      title: "メモリ（旧ファイル）",
+      summary:
+        "以前の 1 ファイル形式のメモリ。旧形式のワークスペースだけが読み込みます。現在のワークスペースは事実を conversations/memory/<type>/<topic>.md の topic ファイルに保存し、このファイルは読まないため、編集しても反映されません。",
     },
     summariesIndex: {
       title: "サマリインデックス",

package/src/lang/ko.ts

@@ -143,6 +143,11 @@ const koMessages = {
     body: "다시 연결하기 전에는 휴대폰에서 이 기기로 보낼 수 없습니다.",
     reconnect: "다시 연결",
   },
+  authTokenStale: {
+    title: "페이지를 새로 고쳐야 합니다",
+    body: "서버가 이 페이지의 토큰을 거부했고 새 토큰을 가져오지 못했습니다. 계속하려면 새로 고침하세요.",
+    reload: "새로 고침",
+  },
   remoteHost: {
     title: "원격 호스트",
     online: "원격 호스트 온라인",
@@ -596,8 +601,9 @@ const koMessages = {
       summary: "시스템 기본 일정 위에 덮어쓰는 작업별 시간 / 간격 오버라이드. 반복 작업 시간을 변경해 달라고 요청하면 에이전트가 여기에 기록합니다.",
     },
     schedulerItems: {
-      title: "스케줄러 아이템 큐",
-      summary: "발화 대기 중인 예약 호출 큐. 에이전트 관리 — 각 필드의 의미를 정확히 알지 않으면 수동 편집하지 마세요.",
+      title: "이전 캘린더 항목",
+      summary:
+        "삭제된 캘린더 화면의 항목입니다. 앱에 표시되지 않으며 일정에 따라 실행되지도 않습니다. 이 파일을 읽고 쓰는 것은 이전 /api/scheduler 작업뿐입니다. 예약 작업은 config/scheduler/tasks.json에 있습니다.",
     },
     wikiIndex: {
       title: "위키 인덱스",
@@ -616,8 +622,9 @@ const koMessages = {
       summary: "에이전트가 위키 페이지 일관성을 유지하기 위해 참조하는 형식 명세. 취약 — 특정 구조를 기대하므로 에이전트 주도 편집을 권장합니다.",
     },
     memory: {
-      title: "메모리",
-      summary: "당신에 관한 정제된 사실로, 새 대화의 컨텍스트로 항상 로드됩니다. journal 추출기가 자동으로 추가하며 수동 편집도 가능합니다.",
+      title: "메모리(이전 파일)",
+      summary:
+        "예전의 단일 파일 메모리입니다. 이전 형식의 워크스페이스만 읽습니다. 현재 워크스페이스는 사실을 conversations/memory/<type>/<topic>.md 토픽 파일에 저장하고 이 파일은 읽지 않으므로, 편집해도 반영되지 않습니다.",
     },
     summariesIndex: {
       title: "요약 인덱스",

package/src/lang/pt-BR.ts

@@ -137,6 +137,11 @@ const ptBRMessages = {
     body: "Seu telefone não conseguirá enviar para este dispositivo até você reconectar.",
     reconnect: "Reconectar",
   },
+  authTokenStale: {
+    title: "Esta página precisa ser recarregada",
+    body: "O servidor recusou o token desta página e não foi possível obter um novo. Recarregue para continuar.",
+    reload: "Recarregar",
+  },
   remoteHost: {
     title: "Host remoto",
     online: "Host remoto on-line",
@@ -597,8 +602,9 @@ const ptBRMessages = {
         "Sobrescritas por tarefa de horário / intervalo aplicadas sobre o agendamento do sistema. O agente edita quando você pede para mudar o horário de uma tarefa.",
     },
     schedulerItems: {
-      title: "Fila de itens do agendador",
-      summary: "Invocações agendadas prontas para disparar. Gerenciado pelo agente; não edite manualmente sem entender cada campo.",
+      title: "Itens de calendário antigos",
+      summary:
+        "Itens da visualização de Calendário removida. O app não os mostra mais e nada os executa por agendamento; só as ações antigas de /api/scheduler ainda leem e gravam este arquivo. As tarefas agendadas ficam em config/scheduler/tasks.json.",
     },
     wikiIndex: {
       title: "Índice da wiki",
@@ -618,9 +624,9 @@ const ptBRMessages = {
         "Especificação de formato que o agente lê para manter as páginas da wiki consistentes. Frágil — espera uma estrutura específica; prefira edições via agente.",
     },
     memory: {
-      title: "Memória",
+      title: "Memória (arquivo antigo)",
       summary:
-        "Fatos destilados sobre você, sempre carregados como contexto em novas conversas. O extrator do journal adiciona automaticamente; você também pode editar manualmente.",
+        "A memória antiga em um único arquivo. Só os espaços de trabalho no formato antigo a leem; os atuais guardam os fatos como arquivos de tópico em conversations/memory/<type>/<topic>.md e ignoram este arquivo, então editá-lo não tem efeito neles.",
     },
     summariesIndex: {
       title: "Índice de resumos",

package/src/lang/zh.ts

@@ -138,6 +138,11 @@ const zhMessages = {
     body: "重新连接之前，手机将无法发送到此设备。",
     reconnect: "重新连接",
   },
+  authTokenStale: {
+    title: "此页面需要重新加载",
+    body: "服务器拒绝了此页面的令牌，且无法获取新令牌。请重新加载以继续。",
+    reload: "重新加载",
+  },
   remoteHost: {
     title: "远程主机",
     online: "远程主机在线",
@@ -584,8 +589,9 @@ const zhMessages = {
       summary: "在系统调度之上叠加的每任务时间 / 间隔覆盖。当你要求修改某个定期任务的时间时，代理会写入此文件。",
     },
     schedulerItems: {
-      title: "调度器条目队列",
-      summary: "等待触发的预定调用队列。代理管理；除非你清楚每个字段的含义，否则不要手动编辑。",
+      title: "旧日历条目",
+      summary:
+        "已删除的日历视图中的条目。应用不再显示它们，也不会按计划执行它们；只有旧的 /api/scheduler 操作仍会读写此文件。计划任务位于 config/scheduler/tasks.json。",
     },
     wikiIndex: {
       title: "Wiki 索引",
@@ -604,8 +610,9 @@ const zhMessages = {
       summary: "代理用于保持 Wiki 页面一致性的格式规范。脆弱 — 代理期望特定结构，建议交由代理编辑。",
     },
     memory: {
-      title: "记忆",
-      summary: "关于你的精炼事实，作为新对话的上下文始终加载。journal 提取器会自动追加，也可手动编辑。",
+      title: "记忆（旧文件）",
+      summary:
+        "旧的单文件记忆。只有仍使用旧格式的工作区会读取它；当前工作区把事实保存为 conversations/memory/<type>/<topic>.md 下的主题文件，并忽略此文件，因此编辑它不会生效。",
     },
     summariesIndex: {
       title: "总结索引",

package/src/main.ts

@@ -9,7 +9,7 @@ import App from "./App.vue";
 import router from "./router/index";
 import { installGuards } from "./router/guards";
 import i18n from "./lib/vue-i18n";
-import { setAuthToken } from "./utils/api";
+import { setAuthToken } from "./utils/auth/authToken";
 import { readAuthTokenFromMeta } from "./utils/dom/authTokenMeta";
 import { loadRuntimePlugins } from "./tools/runtimeLoader";
 import { startDevPluginReloadListener } from "./composables/useDevPluginReload";

package/src/utils/api.ts

@@ -25,11 +25,13 @@
 // `!res.ok` branches. Network errors and HTTP errors surface through the
 // same `{ ok: false }` shape.
 //
-// Future extension hooks (see #272 for auth token):
-//   - setAuthToken() populates a module-level token used by every call
-//   - interceptors could go here for logging, retry, metrics
+// The bearer token lives in `./auth/authToken` (set once at bootstrap), and
+// `./auth/authTokenRecovery` replaces it after a server restart (#3438).
+// Interceptors for logging, retry policy or metrics would go here.
 
 import { ref, type Ref } from "vue";
+import { getAuthToken } from "./auth/authToken";
+import { authTokenStale, recoverAuthToken } from "./auth/authTokenRecovery";
 import { errorMessage } from "./errors";
 import { hasStringProp } from "./types";
 
@@ -89,19 +91,6 @@ function isAbortError(err: unknown): boolean {
   return hasStringProp(err, "name") && err.name === "AbortError";
 }
 
-// ── Auth token (populated by bootstrap; consumed by every call) ─────
-
-let authToken: string | null = null;
-
-/**
- * Set the bearer token used on every API call. Call once during app
- * bootstrap, typically after reading a `<meta>` tag or window global
- * populated by the server.
- */
-export function setAuthToken(token: string | null): void {
-  authToken = token;
-}
-
 // ── Types ────────────────────────────────────────────────────────────
 
 export type ApiResult<T> = { ok: true; data: T } | { ok: false; error: string; status: number };
@@ -145,6 +134,7 @@ function buildHeaders(opts: { headers?: Record<string, string> | undefined }, ha
   if (hasBody && headers["Content-Type"] === undefined) {
     headers["Content-Type"] = "application/json";
   }
+  const authToken = getAuthToken();
   if (authToken && headers["Authorization"] === undefined) {
     headers["Authorization"] = `Bearer ${authToken}`;
   }
@@ -275,11 +265,33 @@ async function successResult<T>(res: Response): Promise<ApiResult<T>> {
   }
 }
 
+const UNAUTHORIZED_STATUS = 401;
+
+/**
+ * Issue `request`, and once more after a 401. A 401 is what a server restart
+ * looks like from a page that stayed open: the token was regenerated and this
+ * page still presents the old one (#3438). index.html carries the new one, so
+ * the token is fetched again and the request re-issued — only when a
+ * DIFFERENT token was installed; `request` builds its headers per call, so
+ * the second issue presents it. A 401 the server sends for its own reasons
+ * (`/api/remote-host/reconnect` on an expired blob) leaves the token
+ * unchanged and reaches the caller as is, and a token the server refuses
+ * twice is reported through `authTokenStale` rather than retried again.
+ */
+async function withTokenRecovery(request: () => Promise<Response>): Promise<Response> {
+  const first = await request();
+  if (first.status !== UNAUTHORIZED_STATUS) return first;
+  if ((await recoverAuthToken()) !== "installed") return first;
+  const retried = await request();
+  if (retried.status === UNAUTHORIZED_STATUS) authTokenStale.value = true;
+  return retried;
+}
+
 export async function apiCall<T = unknown>(path: string, opts: ApiOptions = {}): Promise<ApiResult<T>> {
   const url = `${path}${buildQueryString(opts.query)}`;
   let res: Response;
   try {
-    res = await fetch(url, buildInit(opts));
+    res = await withTokenRecovery(() => fetch(url, buildInit(opts)));
   } catch (err) {
     return transportFailure<T>(err);
   }
@@ -321,17 +333,28 @@ export interface RawOptions {
 /**
  * Escape hatch for endpoints returning binary / streaming / non-JSON
  * bodies (PDF download, audio blob, SSE, etc.). Auth header is still
- * applied; other handling is the caller's responsibility.
+ * applied, and a 401 is retried once with a recovered token the same way
+ * `apiCall` does it; other handling is the caller's responsibility.
  *
  * Throws on network errors. Does NOT check `res.ok`.
  */
-export async function apiFetchRaw(path: string, opts: RawOptions = {}): Promise<Response> {
-  const url = `${path}${buildQueryString(opts.query)}`;
-  const init: FetchInit = {
+function buildRawInit(opts: RawOptions): FetchInit {
+  return {
     method: opts.method ?? "GET",
     headers: buildHeaders(opts, false),
     ...(opts.body !== undefined ? { body: opts.body } : {}),
     ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
   };
-  return fetch(url, init);
+}
+
+/** A stream is consumed by the first issue, so a request carrying one
+ *  cannot be re-issued after a 401; every other body fetch accepts can. */
+function isReplayableBody(body: RawOptions["body"]): boolean {
+  return !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream);
+}
+
+export async function apiFetchRaw(path: string, opts: RawOptions = {}): Promise<Response> {
+  const url = `${path}${buildQueryString(opts.query)}`;
+  const request = (): Promise<Response> => fetch(url, buildRawInit(opts));
+  return isReplayableBody(opts.body) ? withTokenRecovery(request) : request();
 }

package/src/utils/auth/authToken.ts

@@ -0,0 +1,14 @@
+// The bearer token every call presents, read once from index.html at
+// bootstrap (`src/main.ts`) and replaced after a server restart
+// (`authTokenRecovery.ts`). A module so that `api.ts`, the `/ws/pubsub`
+// handshake and the recovery read one value.
+
+let authToken: string | null = null;
+
+export function setAuthToken(token: string | null): void {
+  authToken = token;
+}
+
+export function getAuthToken(): string | null {
+  return authToken;
+}

package/src/utils/auth/authTokenHtml.ts

@@ -0,0 +1,19 @@
+// The served index.html carries the bearer token in
+// `<meta name="mulmoclaude-auth" content="…">`: the production handler and the
+// Vite dev plugin substitute it on every request. Pure string work, so the
+// page can read a token out of a re-fetched index.html without a DOM.
+
+export const AUTH_TOKEN_META_NAME = "mulmoclaude-auth";
+
+const META_TAGS = /<meta\b[^>]*>/gi;
+const AUTH_META_NAME_ATTRIBUTE = new RegExp(`\\bname\\s*=\\s*"${AUTH_TOKEN_META_NAME}"`, "i");
+const CONTENT_ATTRIBUTE = /\bcontent\s*=\s*"([^"]*)"/i;
+
+/** The token `html` carries, `null` when the tag is missing or its content is
+ *  empty — the same two cases `readAuthTokenFromMeta` reads as "no token". */
+export function extractAuthTokenFromHtml(html: string): string | null {
+  const authMetaTag = (html.match(META_TAGS) ?? []).find((tag) => AUTH_META_NAME_ATTRIBUTE.test(tag));
+  if (authMetaTag === undefined) return null;
+  const content = CONTENT_ATTRIBUTE.exec(authMetaTag)?.[1];
+  return content === undefined || content === "" ? null : content;
+}

package/src/utils/auth/authTokenRecovery.ts

@@ -0,0 +1,73 @@
+// After a server restart an open page holds a token the server no longer
+// accepts: the token is regenerated at every start, and the page read it once
+// from index.html (#3438). index.html is served without a token and carries
+// the current one on every request — the production handler substitutes it
+// per request, the Vite plugin does the same for a loopback requester — so the
+// page fetches it again instead of asking the user to reload.
+
+import { ref, type Ref } from "vue";
+import { errorMessage } from "../errors";
+import { getAuthToken, setAuthToken } from "./authToken";
+import { extractAuthTokenFromHtml } from "./authTokenHtml";
+
+/** How a recovery ended. `installed`: index.html carried a token other than
+ *  the one the page held, and every later call presents it. `unchanged`: it
+ *  carried the token the server just refused. `unavailable`: it carried none,
+ *  or was not served. `unreachable`: the fetch itself failed. */
+export type AuthTokenRecovery = "installed" | "unchanged" | "unavailable" | "unreachable";
+
+/** True once the server refused this page's token and a fresh one could not
+ *  be fetched. `AuthTokenStaleBanner` offers a reload while it is set. */
+export const authTokenStale: Ref<boolean> = ref(false);
+
+const INDEX_HTML_PATH = "/";
+const INDEX_HTML_FETCH_TIMEOUT_MS = 10_000;
+
+/** What a fetched token means for a page holding `held`. */
+export function recoveryOutcome(held: string | null, fetched: string | null): Exclude<AuthTokenRecovery, "unreachable"> {
+  if (fetched === null) return "unavailable";
+  return fetched === held ? "unchanged" : "installed";
+}
+
+/** The served index.html, `null` when it could not be fetched at all. A reply
+ *  other than 2xx is a server that answered without a token, not an outage. */
+async function fetchIndexHtml(): Promise<string | null> {
+  const timeoutController = new AbortController();
+  const timeoutTimer = setTimeout(() => timeoutController.abort(), INDEX_HTML_FETCH_TIMEOUT_MS);
+  try {
+    const indexHtmlResponse = await fetch(INDEX_HTML_PATH, { cache: "no-store", signal: timeoutController.signal });
+    return indexHtmlResponse.ok ? await indexHtmlResponse.text() : "";
+  } catch (err) {
+    console.warn(`[authTokenRecovery] could not fetch ${INDEX_HTML_PATH}:`, errorMessage(err));
+    return null;
+  } finally {
+    clearTimeout(timeoutTimer);
+  }
+}
+
+async function runRecovery(): Promise<AuthTokenRecovery> {
+  const html = await fetchIndexHtml();
+  if (html === null) return "unreachable";
+  const fetchedToken = extractAuthTokenFromHtml(html);
+  const outcome = recoveryOutcome(getAuthToken(), fetchedToken);
+  if (outcome === "installed") {
+    setAuthToken(fetchedToken);
+    authTokenStale.value = false;
+  } else if (outcome === "unavailable") {
+    authTokenStale.value = true;
+  }
+  return outcome;
+}
+
+let inFlightRecovery: Promise<AuthTokenRecovery> | null = null;
+
+/** Fetch index.html again and install the token it carries. Concurrent
+ *  callers — every 401 of a burst, plus the socket refusal — share one fetch. */
+export function recoverAuthToken(): Promise<AuthTokenRecovery> {
+  if (inFlightRecovery === null) {
+    inFlightRecovery = runRecovery().finally(() => {
+      inFlightRecovery = null;
+    });
+  }
+  return inFlightRecovery;
+}

package/src/utils/dom/authTokenMeta.ts

@@ -11,8 +11,10 @@
 //     available; every subsequent API call will 401, which is the
 //     correct dev-time signal)
 
+import { AUTH_TOKEN_META_NAME } from "../auth/authTokenHtml";
+
 export function readAuthTokenFromMeta(): string | null {
-  const meta = document.querySelector('meta[name="mulmoclaude-auth"]');
+  const meta = document.querySelector(`meta[name="${AUTH_TOKEN_META_NAME}"]`);
   if (meta === null) return null;
   const content = meta.getAttribute("content");
   if (content === null || content === "") return null;