mulmoclaude 2.3.0 → 2.4.1

package/server/workspace/memory/run.ts

@@ -22,6 +22,9 @@ import path from "node:path";
 import { runClaudeCli, ClaudeCliNotFoundError, type Summarize } from "../journal/archivist-cli.js";
 import { makeLlmMemoryClassifier } from "./llm-classifier.js";
 import { migrateLegacyMemory } from "./migrate.js";
+import { decideLegacyMigration, type LegacyMemoryState, type LegacyMigrationSkipReason } from "./legacy-migration-gate.js";
+import { hasTopicFormat } from "./topic-detect.js";
+import { WORKSPACE_FILES } from "../paths.js";
 import { errorMessage } from "../../utils/errors.js";
 import { log } from "../../system/logger/index.js";
 
@@ -32,35 +35,11 @@ export interface RunMigrationDeps {
 }
 
 export async function runMemoryMigrationOnce(workspaceRoot: string, deps: RunMigrationDeps = {}): Promise<void> {
-  const legacyPath = path.join(workspaceRoot, "conversations", "memory.md");
-  if (!existsSync(legacyPath)) {
-    log.debug("memory", "migration: no legacy file, skipping");
-    return;
-  }
-  // If the file is suspiciously empty (just the placeholder we used
-  // to write at init), skip — the migration would yield zero entries
-  // and the rename to `.backup` is pointless.
-  const stat = statSync(legacyPath);
-  if (stat.size < 64) {
-    log.info("memory", "migration: legacy file is below the placeholder threshold, skipping");
-    return;
-  }
-  // The rename to `.backup` is the final step of `migrateLegacyMemory`,
-  // so its presence is the "migration completed" marker. A workspace
-  // where both `memory.md` AND `memory.md.backup` exist means the
-  // user re-introduced the legacy file after a previous successful
-  // migration (probably by mistake or by extracting the backup).
-  // Re-running here would re-classify the bullets and could clobber
-  // typed entries the user has been editing in place; skip with a
-  // clear log instead. The interrupted-migration retry case still
-  // works because no `.backup` exists in that state — the rename
-  // never ran.
+  const legacyPath = path.join(workspaceRoot, WORKSPACE_FILES.memory);
   const backupPath = `${legacyPath}.backup`;
-  if (existsSync(backupPath)) {
-    log.info("memory", "migration: legacy file present but .backup also exists — refusing to re-run", {
-      legacyPath,
-      backupPath,
-    });
+  const gate = decideLegacyMigration(readLegacyMemoryState(workspaceRoot, legacyPath, backupPath));
+  if (!gate.run) {
+    logSkip(gate.reason, legacyPath, backupPath);
     return;
   }
   const summarize = deps.summarize ?? runClaudeCli;
@@ -73,6 +52,7 @@ export async function runMemoryMigrationOnce(workspaceRoot: string, deps: RunMig
       written: result.written,
       skippedByClassifier: result.skippedByClassifier,
       writeErrors: result.writeErrors,
+      classifierFailures: result.classifierFailures,
     });
   } catch (err) {
     if (err instanceof ClaudeCliNotFoundError) {
@@ -82,3 +62,27 @@ export async function runMemoryMigrationOnce(workspaceRoot: string, deps: RunMig
     log.error("memory", "migration: threw, legacy memory left in place", { error: errorMessage(err) });
   }
 }
+
+function readLegacyMemoryState(workspaceRoot: string, legacyPath: string, backupPath: string): LegacyMemoryState {
+  let legacySizeBytes: number | null = null;
+  try {
+    legacySizeBytes = statSync(legacyPath).size;
+  } catch {
+    // ENOENT (or a rename racing us) → treat as absent.
+  }
+  return { legacySizeBytes, backupExists: existsSync(backupPath), topicFormat: hasTopicFormat(workspaceRoot) };
+}
+
+function logSkip(reason: LegacyMigrationSkipReason, legacyPath: string, backupPath: string): void {
+  if (reason === "no-legacy-file") {
+    log.debug("memory", "migration: no legacy file, skipping");
+  } else if (reason === "topic-format") {
+    log.info("memory", "migration: workspace uses topic format, leaving legacy file alone", { legacyPath });
+  } else if (reason === "placeholder") {
+    log.info("memory", "migration: legacy file is below the placeholder threshold, skipping");
+  } else {
+    // A previous run renamed memory.md to .backup as its last step, so the user re-introduced the
+    // file; re-classifying it could clobber typed entries they have been editing.
+    log.info("memory", "migration: legacy file present but .backup also exists — refusing to re-run", { legacyPath, backupPath });
+  }
+}

package/server/workspace/memory/seed-topic-layout-run.ts

@@ -0,0 +1,50 @@
+import { lstatSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { WORKSPACE_DIRS, WORKSPACE_FILES } from "../paths.js";
+import { MEMORY_TYPES } from "./types.js";
+import { shouldSeedTopicLayout, type MemoryLayoutState } from "./seed-topic-layout.js";
+import { errorMessage } from "../../utils/errors.js";
+import { log } from "../../system/logger/index.js";
+
+// `undefined` = could not be read for a reason other than absence.
+type ReadResult<T> = T | null | undefined;
+
+function isNotFound(err: unknown): boolean {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+
+function readOrMissing<T>(read: () => T): ReadResult<T> {
+  try {
+    return read();
+  } catch (err) {
+    return isNotFound(err) ? null : undefined;
+  }
+}
+
+function readMemoryLayoutState(workspaceRoot: string): MemoryLayoutState {
+  const entries = readOrMissing(() => readdirSync(path.join(workspaceRoot, WORKSPACE_DIRS.memoryDir)));
+  const legacyText = readOrMissing(() => readFileSync(path.join(workspaceRoot, WORKSPACE_FILES.memory), "utf-8"));
+  // lstat, not existsSync: a broken symlink or a permission error must not read as "no staging".
+  const staging = readOrMissing(() => lstatSync(path.join(workspaceRoot, WORKSPACE_DIRS.memoryStaging)));
+  return {
+    memoryDirEntries: entries ?? [],
+    legacyMemoryText: legacyText ?? null,
+    stagingExists: staging !== null,
+    unreadable: entries === undefined || legacyText === undefined || staging === undefined,
+  };
+}
+
+/** Create the topic-layout type directories when the workspace has no memory to lose. Returns whether it did.
+ *  Never throws: boot must not depend on it. */
+export function seedTopicLayoutIfFresh(workspaceRoot: string): boolean {
+  if (!shouldSeedTopicLayout(readMemoryLayoutState(workspaceRoot))) return false;
+  const memoryRoot = path.join(workspaceRoot, WORKSPACE_DIRS.memoryDir);
+  try {
+    MEMORY_TYPES.forEach((type) => mkdirSync(path.join(memoryRoot, type), { recursive: true }));
+    return true;
+  } catch (err) {
+    log.warn("memory", "could not create the topic memory layout; staying on the atomic one", { memoryRoot, error: errorMessage(err) });
+    return false;
+  }
+}

package/server/workspace/memory/seed-topic-layout.ts

@@ -0,0 +1,34 @@
+// Whether a workspace may start directly in the topic memory layout (#1070) instead of passing through the
+// atomic one. Only when there is no memory to lose: anything else must go through the migration chain.
+
+// What `initWorkspace` used to write into a fresh `memory.md` before #1029; it holds no facts.
+export const LEGACY_MEMORY_PLACEHOLDER = "# Memory\n\nDistilled facts about you and your work.\n";
+
+// Entries that can sit in an empty memory dir: the atomic layout's generated index and Finder metadata.
+// Anything else — including a `.atomic-backup-*` dir, which can hold entries — means there is memory to keep.
+const HARMLESS_MEMORY_DIR_ENTRIES: ReadonlySet<string> = new Set(["MEMORY.md", ".DS_Store"]);
+
+export interface MemoryLayoutState {
+  /** Names directly under `conversations/memory/`; empty when the directory is absent. */
+  memoryDirEntries: readonly string[];
+  /** Contents of `conversations/memory.md`, or null when absent. */
+  legacyMemoryText: string | null;
+  /** `conversations/memory.next/` exists — a topic migration is staged or mid-swap. */
+  stagingExists: boolean;
+  /** Something could not be read (other than "does not exist"), so the state is unknown. */
+  unreadable: boolean;
+}
+
+function normaliseText(text: string): string {
+  return text.replace(/^\uFEFF/u, "").replace(/\r\n/g, "\n");
+}
+
+export function isLegacyMemoryPlaceholder(text: string): boolean {
+  return normaliseText(text) === LEGACY_MEMORY_PLACEHOLDER;
+}
+
+export function shouldSeedTopicLayout(state: MemoryLayoutState): boolean {
+  if (state.unreadable || state.stagingExists) return false;
+  if (state.legacyMemoryText !== null && !isLegacyMemoryPlaceholder(state.legacyMemoryText)) return false;
+  return state.memoryDirEntries.every((name) => HARMLESS_MEMORY_DIR_ENTRIES.has(name));
+}

package/server/workspace/memory/startup.ts

@@ -0,0 +1,29 @@
+// Boot-time memory migration chain plus the promise other subsystems wait on before touching
+// `conversations/memory.md` — the journal's extractor appending mid-migration loses those bullets.
+
+import { runMemoryMigrationOnce } from "./run.js";
+import { runTopicMigrationOnce } from "./topic-run.js";
+
+export type MemoryMigrationRunner = (workspaceRoot: string) => Promise<void>;
+
+const DEFAULT_RUNNERS: readonly MemoryMigrationRunner[] = [runMemoryMigrationOnce, runTopicMigrationOnce];
+
+let migrationsSettled: Promise<void> = Promise.resolve();
+
+// Chained so a second start never lets the journal slip past a chain that is still running.
+export function startMemoryMigrations(workspaceRoot: string, runners: readonly MemoryMigrationRunner[] = DEFAULT_RUNNERS): void {
+  migrationsSettled = migrationsSettled.then(() => runInOrder(workspaceRoot, runners));
+}
+
+// Never rejects: a failed migration must not wedge the journal behind it.
+export function memoryMigrationsSettled(): Promise<void> {
+  return migrationsSettled;
+}
+
+async function runInOrder(workspaceRoot: string, runners: readonly MemoryMigrationRunner[]): Promise<void> {
+  try {
+    await runners.reduce<Promise<void>>((previous, runner) => previous.then(() => runner(workspaceRoot)), Promise.resolve());
+  } catch {
+    // Each runner logs its own failure; stopping the chain here matches the previous `.then(noop, noop)`.
+  }
+}

package/server/workspace/memory/topic-migrate.ts

@@ -3,8 +3,8 @@
 // Reads the existing #1029-style atomic entries from
 // `conversations/memory/`, runs a clusterer, and writes the
 // proposed topic layout to a STAGING dir
-// `conversations/memory.next/`. Does NOT swap. The user runs
-// `topic-swap.ts` after reviewing.
+// `conversations/memory.next/`. Does NOT swap — `runTopicMigrationOnce`
+// does that right after. A cluster that dropped bullets is never staged.
 //
 // Library only — `runTopicMigrationOnce` (in PR-B) decides when
 // to call this from server startup.
@@ -13,13 +13,16 @@
 // the one-shot atomic → topic migration chain and goes when the
 // chain goes.
 
-import { mkdir, rm } from "node:fs/promises";
+import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 
 import { writeFileAtomic } from "../../utils/files/atomic.js";
+import { readTextSafe } from "../../utils/files/safe.js";
 import { log } from "../../system/logger/index.js";
 import { errorMessage } from "../../utils/errors.js";
-import { WORKSPACE_DIRS } from "../paths.js";
+import { WORKSPACE_DIRS, WORKSPACE_FILES } from "../paths.js";
+import { parseCandidates } from "./migrate.js";
+import { legacyFoldEntries } from "./legacy-fold.js";
 import { loadAllMemoryEntries } from "./io.js";
 import { MEMORY_TYPES, type MemoryEntry, type MemoryType } from "./types.js";
 import type { ClusterMap, ClusterTopic, MemoryClusterer } from "./topic-cluster.js";
@@ -42,6 +45,38 @@ export function topicStagingPath(workspaceRoot: string): string {
   return path.join(workspaceRoot, WORKSPACE_DIRS.memoryStaging);
 }
 
+// Written last, so its presence means every topic file was staged.
+const STAGING_INDEX_FILE = "MEMORY.md";
+
+export function stagingIndexPath(stagingPath: string): string {
+  return path.join(stagingPath, STAGING_INDEX_FILE);
+}
+
+async function countBulletLines(file: string): Promise<number> {
+  const text = await readTextSafe(file);
+  return text === null ? 0 : text.split("\n").filter((line) => line.startsWith("- ")).length;
+}
+
+async function countStagedBullets(stagingPath: string): Promise<number> {
+  const perType = await Promise.all(
+    MEMORY_TYPES.map(async (type) => {
+      const dir = path.join(stagingPath, type);
+      const names = await readdir(dir).catch(() => []);
+      const counts = await Promise.all(names.filter((name) => name.endsWith(".md")).map((name) => countBulletLines(path.join(dir, name))));
+      return counts.reduce((total, count) => total + count, 0);
+    }),
+  );
+  return perType.reduce((total, count) => total + count, 0);
+}
+
+/** A leftover staging may be swapped only if it was fully written (index present) and holds a bullet for every
+ *  input the cluster would take (`countClusterInput`) — the index alone is not enough, because builds before #3458
+ *  indexed lossy stagings too, and builds before #3460 did not stage leftover `memory.md` bullets. */
+export async function isStagingSwappable(stagingPath: string, requiredBulletCount: number): Promise<boolean> {
+  if ((await readTextSafe(stagingIndexPath(stagingPath))) === null) return false;
+  return (await countStagedBullets(stagingPath)) >= requiredBulletCount;
+}
+
 interface WrittenTopic {
   type: MemoryType;
   topic: ClusterTopic;
@@ -51,29 +86,63 @@ interface WrittenTopic {
 }
 
 export async function clusterAtomicIntoStaging(workspaceRoot: string, clusterer: MemoryClusterer): Promise<TopicMigrationResult> {
-  const entries = await loadAllMemoryEntries(workspaceRoot);
+  const { atomicEntries, foldedEntries } = await loadClusterInput(workspaceRoot);
   const stagingPath = topicStagingPath(workspaceRoot);
-  if (entries.length === 0) return emptyResult(stagingPath);
-  log.info("memory", "topic-migrate: clustering", { entryCount: entries.length });
+  if (atomicEntries.length === 0) return emptyResult(stagingPath);
+  const entries = [...atomicEntries, ...foldedEntries];
+  log.info("memory", "topic-migrate: clustering", { entryCount: entries.length, foldedFromMemoryMd: foldedEntries.length });
 
   const map = await runClustererOrCleanup(entries, stagingPath, clusterer);
   if (!map) return { ...emptyResult(stagingPath), inputCount: entries.length };
+  // Checked before anything is written: a lossy staging left by a crash would be promoted by the retry-swap path.
+  const bulletsLost = countBulletsLost(entries, map);
+  if (bulletsLost > 0) {
+    log.warn("memory", "topic-migrate: cluster dropped bullets, not staging it; the atomic layout stays", { bulletsLost });
+    await rm(stagingPath, { recursive: true, force: true });
+    return { ...emptyResult(stagingPath), inputCount: entries.length, bulletsLost };
+  }
 
   const topicCounts: Record<MemoryType, number> = { preference: 0, interest: 0, fact: 0, reference: 0 };
   const written = await writeTopicsToStaging(stagingPath, map, topicCounts);
+  const topicsInCluster = MEMORY_TYPES.reduce((total, type) => total + map[type].length, 0);
+  if (written.length < topicsInCluster) {
+    // The index marks a staging complete for the retry-swap path, so a partial tree must not get one.
+    log.warn("memory", "topic-migrate: some topic files failed to stage, discarding the staging", { written: written.length, topicsInCluster });
+    await rm(stagingPath, { recursive: true, force: true });
+    return { ...emptyResult(stagingPath), inputCount: entries.length };
+  }
   await writeStagingIndex(stagingPath, written);
 
   const result: TopicMigrationResult = {
     noop: false,
     inputCount: entries.length,
     topicCounts,
-    bulletsLost: countBulletsLost(entries, map),
+    bulletsLost,
     stagingPath,
   };
   log.info("memory", "topic-migrate: staging ready", { stagingPath, topicCounts, bulletsLost: result.bulletsLost });
   return result;
 }
 
+interface ClusterInput {
+  atomicEntries: MemoryEntry[];
+  /** Bullets from a leftover `memory.md` that the cluster must also place (#3460). */
+  foldedEntries: MemoryEntry[];
+}
+
+async function loadClusterInput(workspaceRoot: string): Promise<ClusterInput> {
+  const atomicEntries = await loadAllMemoryEntries(workspaceRoot);
+  const legacyText = await readTextSafe(path.join(workspaceRoot, WORKSPACE_FILES.memory));
+  const foldedEntries = legacyText === null ? [] : legacyFoldEntries(parseCandidates(legacyText), atomicEntries);
+  return { atomicEntries, foldedEntries };
+}
+
+/** How many bullets a staging must hold to cover this workspace's memory — the same input the cluster takes. */
+export async function countClusterInput(workspaceRoot: string): Promise<number> {
+  const { atomicEntries, foldedEntries } = await loadClusterInput(workspaceRoot);
+  return atomicEntries.length + foldedEntries.length;
+}
+
 // Wipe stale staging BEFORE the cluster call. If the clusterer
 // returns null or throws, we leave the workspace with no staging
 // dir at all — that's the correct "migration didn't complete"
@@ -233,7 +302,7 @@ async function writeStagingIndex(stagingPath: string, written: WrittenTopic[]):
   if (written.length === 0) {
     lines.push("_(no entries yet)_", "");
   }
-  await writeFileAtomic(path.join(stagingPath, "MEMORY.md"), lines.join("\n"), { uniqueTmp: true });
+  await writeFileAtomic(stagingIndexPath(stagingPath), lines.join("\n"), { uniqueTmp: true });
 }
 
 function formatStagingIndexLine(entry: WrittenTopic): string {

package/server/workspace/memory/topic-run.ts

@@ -27,13 +27,15 @@
 // `topic-detect.ts` — minus the atomic-format branch) stays.
 
 import { existsSync, statSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import path from "node:path";
 
 import { runClaudeCli, ClaudeCliNotFoundError, type Summarize } from "../journal/archivist-cli.js";
 import { WORKSPACE_DIRS, WORKSPACE_FILES } from "../paths.js";
+import { LEGACY_MEMORY_PLACEHOLDER_MAX_BYTES } from "./legacy-migration-gate.js";
 import { loadAllMemoryEntries } from "./io.js";
 import { makeLlmMemoryClusterer, type MemoryClusterer } from "./topic-cluster.js";
-import { clusterAtomicIntoStaging, topicStagingPath } from "./topic-migrate.js";
+import { clusterAtomicIntoStaging, countClusterInput, isStagingSwappable, topicStagingPath } from "./topic-migrate.js";
 import { swapStagingIntoMemory } from "./topic-swap.js";
 import { MEMORY_TYPES } from "./types.js";
 import { errorMessage } from "../../utils/errors.js";
@@ -71,14 +73,17 @@ export async function runTopicMigrationOnce(workspaceRoot: string, deps: RunTopi
     return;
   }
   const stagingPath = topicStagingPath(workspaceRoot);
-  // If staging is left over from a prior run that crashed between
-  // cluster and swap, just retry the swap. Re-clustering would burn
-  // another LLM call and (because clusterAtomicIntoStaging wipes
-  // staging up front) discard the prior cluster result.
+  // A complete staging left by a crash between cluster and swap is swapped without another LLM call. An
+  // incomplete one (crash during the cluster call or mid-write) would replace memory/ with a partial tree, so it
+  // is discarded and the cluster runs again below.
   if (existsSync(stagingPath)) {
-    log.info("memory", "topic-run: existing staging detected, retrying swap", { stagingPath });
-    await runSwap(workspaceRoot);
-    return;
+    if (await isStagingSwappable(stagingPath, await countClusterInput(workspaceRoot))) {
+      log.info("memory", "topic-run: existing staging detected, retrying swap", { stagingPath });
+      await runSwap(workspaceRoot);
+      return;
+    }
+    log.warn("memory", "topic-run: discarding an incomplete or lossy staging from an interrupted run", { stagingPath });
+    await rm(stagingPath, { recursive: true, force: true });
   }
   if (shouldDeferForLegacyMigration(workspaceRoot)) return;
 
@@ -119,7 +124,7 @@ function shouldDeferForLegacyMigration(workspaceRoot: string): boolean {
   } catch {
     legacyStat = null;
   }
-  if (legacyStat && legacyStat.size >= 64 && !existsSync(`${legacyPath}.backup`)) {
+  if (legacyStat && legacyStat.size >= LEGACY_MEMORY_PLACEHOLDER_MAX_BYTES && !existsSync(`${legacyPath}.backup`)) {
     log.debug("memory", "topic-run: legacy memory.md still in flight, deferring", { legacyPath });
     return true;
   }

package/server/workspace/memory/topic-swap.ts

@@ -1,10 +1,8 @@
-// Swap `conversations/memory/` ↔ `conversations/memory.next/`
-// after the user has approved the staging diff (#1070 PR-A).
+// Swap `conversations/memory/` ↔ `conversations/memory.next/` (#1070 PR-A).
 //
-// Library only — invoked from a CLI helper or the agent (a tool
-// surface for the agent will land later). The swap is intentionally
-// NOT auto-run: the whole point of staging is to give the user a
-// chance to inspect.
+// Run automatically by `runTopicMigrationOnce` right after staging,
+// (a cluster that dropped bullets is never staged, so the workspace stays
+// atomic). `yarn memory:swap` runs it by hand.
 //
 // CLEANUP 2026-07-01: see `topic-run.ts` — this file is part of
 // the one-shot atomic → topic migration chain and goes when the

package/server/workspace/workspace.ts

@@ -5,6 +5,7 @@ import { log } from "../system/logger/index.js";
 import { EAGER_WORKSPACE_DIRS, WORKSPACE_PATHS, workspacePath } from "./paths.js";
 import { readWorkspaceTextSync, writeWorkspaceTextSync } from "../utils/files/workspace-io.js";
 import { loadCustomDirs, ensureCustomDirs } from "./custom-dirs.js";
+import { seedTopicLayoutIfFresh } from "./memory/seed-topic-layout-run.js";
 // Helps + preset skills + their sync logic now live in @mulmoclaude/core/workspace-setup
 // (shared with MulmoTerminal); the bundled source dirs come from the package.
 import { seedHelps, presetSkillsAssetDir, syncActivePresetSkills, syncPresetSkills } from "@mulmoclaude/core/workspace-setup";
@@ -23,14 +24,10 @@ export function initWorkspace(): string {
     mkdirSync(WORKSPACE_PATHS[key], { recursive: true });
   }
 
-  // Ensure the typed-memory directory exists (#1029). Individual
-  // entry files are written by the agent or by the legacy-memory
-  // migration; init just guarantees the directory is there so the
-  // reader and migration both have a place to write to. The legacy
-  // `conversations/memory.md` is no longer auto-created — migration
-  // converts it on first start and the new layout becomes the source
-  // of truth thereafter.
+  // Ensure the memory directory exists. A workspace with no memory to lose starts directly in the
+  // topic layout (#1070); one that has any goes through the boot-time migration chain instead.
   mkdirSync(WORKSPACE_PATHS.memoryDir, { recursive: true });
+  if (seedTopicLayoutIfFresh(workspacePath)) log.info("memory", "new workspace: starting in the topic memory layout");
 
   // Always sync the bundled help docs into workspace/helps/.
   seedHelps({ destDir: WORKSPACE_PATHS.helps });

package/src/App.vue

@@ -4,6 +4,10 @@
          it's the first thing the user sees when the server isn't
          reachable. Self-hiding when fetchHealth succeeds. -->
     <BackendOfflineBanner :on-retry="fetchHealth" />
+    <!-- Stale-token notice (#3438) — the server refused this page's token and
+         fetching index.html again did not produce one it accepts. Recovery is
+         the normal path after a restart; this is its last resort. -->
+    <AuthTokenStaleBanner />
     <!-- Remote-host disconnect notice (#2535) — shown when the host was meant to
          be connected (a session is parked) but dropped and a silent reconnect
          couldn't restore it. Offers a one-click re-login. -->
@@ -361,6 +365,7 @@ import { ref, computed, watch, nextTick, onMounted, onScopeDispose, reactive } f
 import { useI18n } from "vue-i18n";
 import { getPlugin } from "./tools";
 import type { ToolResultComplete } from "gui-chat-protocol/vue";
+import AuthTokenStaleBanner from "./components/AuthTokenStaleBanner.vue";
 import BackendOfflineBanner from "./components/BackendOfflineBanner.vue";
 import RemoteHostOfflineBanner from "./components/RemoteHostOfflineBanner.vue";
 import RightSidebar from "./components/RightSidebar.vue";

package/src/components/AuthTokenStaleBanner.vue

@@ -0,0 +1,27 @@
+<template>
+  <StatusBanner
+    v-if="authTokenStale"
+    tone="warning"
+    icon="sync_disabled"
+    testid="auth-token-stale-banner"
+    action-testid="auth-token-stale-reload"
+    :title="t('authTokenStale.title')"
+    :body="t('authTokenStale.body')"
+    :action-label="t('authTokenStale.reload')"
+    @action="reload"
+  />
+</template>
+
+<script setup lang="ts">
+// Shown once the server refused this page's token and fetching index.html
+// again did not produce one it accepts (#3438). Auto-recovery is the normal
+// path after a server restart; this is its last resort, and a reload is the
+// only thing left that fetches a fresh token.
+import { useI18n } from "vue-i18n";
+import StatusBanner from "./StatusBanner.vue";
+import { authTokenStale } from "../utils/auth/authTokenRecovery";
+
+const { t } = useI18n();
+
+const reload = (): void => window.location.reload();
+</script>

package/src/components/BackendOfflineBanner.vue

@@ -1,34 +1,23 @@
 <template>
-  <div
+  <StatusBanner
     v-if="!backendReachable"
-    data-testid="backend-offline-banner"
-    role="alert"
-    class="flex items-center gap-2 px-3 py-2 bg-red-50 border-b border-red-200 text-red-700 text-sm"
-  >
-    <span class="material-icons text-base" aria-hidden="true">cloud_off</span>
-    <div class="flex-1 min-w-0">
-      <div class="font-medium">{{ t("backendOffline.title") }}</div>
-      <div class="text-xs text-red-600 truncate">
-        <span>{{ t("backendOffline.body") }}</span>
-        <span v-if="lastBackendError" class="opacity-70">{{ ` — ${lastBackendError}` }}</span>
-      </div>
-    </div>
-    <button
-      type="button"
-      data-testid="backend-offline-retry"
-      class="h-8 px-2.5 flex items-center gap-1 text-sm rounded border border-red-300 text-red-700 hover:bg-red-100 disabled:opacity-40"
-      :disabled="retrying"
-      @click="retry"
-    >
-      <span class="material-icons text-sm" :class="retrying ? 'animate-spin' : ''" aria-hidden="true">refresh</span>
-      {{ t("backendOffline.retry") }}
-    </button>
-  </div>
+    tone="error"
+    icon="cloud_off"
+    testid="backend-offline-banner"
+    action-testid="backend-offline-retry"
+    :title="t('backendOffline.title')"
+    :body="t('backendOffline.body')"
+    :detail="lastBackendError"
+    :action-label="t('backendOffline.retry')"
+    :busy="retrying"
+    @action="retry"
+  />
 </template>
 
 <script setup lang="ts">
 import { ref } from "vue";
 import { useI18n } from "vue-i18n";
+import StatusBanner from "./StatusBanner.vue";
 import { backendReachable, lastBackendError } from "../utils/api";
 
 const { t } = useI18n();

package/src/components/RemoteHostOfflineBanner.vue

@@ -1,26 +1,16 @@
 <template>
-  <div
+  <StatusBanner
     v-if="needsReconnect"
-    data-testid="remote-host-offline-banner"
-    role="alert"
-    class="flex items-center gap-2 px-3 py-2 bg-amber-50 border-b border-amber-200 text-amber-800 text-sm"
-  >
-    <span class="material-icons text-base" aria-hidden="true">phonelink_off</span>
-    <div class="flex-1 min-w-0">
-      <div class="font-medium">{{ t("remoteHostOffline.title") }}</div>
-      <div class="text-xs text-amber-700 truncate">{{ t("remoteHostOffline.body") }}</div>
-    </div>
-    <button
-      type="button"
-      data-testid="remote-host-offline-reconnect"
-      class="h-8 px-2.5 flex items-center gap-1 text-sm rounded border border-amber-300 text-amber-800 hover:bg-amber-100 disabled:opacity-40"
-      :disabled="busy"
-      @click="reconnect"
-    >
-      <span class="material-icons text-sm" :class="busy ? 'animate-spin' : ''" aria-hidden="true">refresh</span>
-      {{ t("remoteHostOffline.reconnect") }}
-    </button>
-  </div>
+    tone="warning"
+    icon="phonelink_off"
+    testid="remote-host-offline-banner"
+    action-testid="remote-host-offline-reconnect"
+    :title="t('remoteHostOffline.title')"
+    :body="t('remoteHostOffline.body')"
+    :action-label="t('remoteHostOffline.reconnect')"
+    :busy="busy"
+    @action="reconnect"
+  />
 </template>
 
 <script setup lang="ts">
@@ -29,6 +19,7 @@
 // session expired). Reads the shared `useRemoteHost` store; Reconnect re-runs the
 // Google sign-in popup from this click (a user gesture, so the popup isn't blocked).
 import { useI18n } from "vue-i18n";
+import StatusBanner from "./StatusBanner.vue";
 import { useRemoteHost } from "../composables/useRemoteHost";
 
 const { t } = useI18n();

package/src/components/StatusBanner.vue

@@ -0,0 +1,65 @@
+<template>
+  <div :data-testid="testid" role="alert" class="flex items-center gap-2 px-3 py-2 border-b text-sm" :class="palette.root">
+    <span class="material-icons text-base" aria-hidden="true">{{ icon }}</span>
+    <div class="flex-1 min-w-0">
+      <div class="font-medium">{{ title }}</div>
+      <div class="text-xs truncate" :class="palette.body">
+        <span>{{ body }}</span>
+        <span v-if="detail" class="opacity-70">{{ ` — ${detail}` }}</span>
+      </div>
+    </div>
+    <button
+      type="button"
+      :data-testid="actionTestid"
+      class="h-8 px-2.5 flex items-center gap-1 text-sm rounded border disabled:opacity-40"
+      :class="palette.button"
+      :disabled="busy"
+      @click="emit('action')"
+    >
+      <span class="material-icons text-sm" :class="busy ? 'animate-spin' : ''" aria-hidden="true">refresh</span>
+      {{ actionLabel }}
+    </button>
+  </div>
+</template>
+
+<script setup lang="ts">
+// The one chrome for a page-wide status notice pinned above the top bar: an
+// icon, a title, one line of body with optional small print, and one action.
+// The wrapper that mounts it owns the signal (`v-if`) and the action.
+import { computed } from "vue";
+
+const PALETTES = {
+  error: {
+    root: "bg-red-50 border-red-200 text-red-700",
+    body: "text-red-600",
+    button: "border-red-300 text-red-700 hover:bg-red-100",
+  },
+  warning: {
+    root: "bg-amber-50 border-amber-200 text-amber-800",
+    body: "text-amber-700",
+    button: "border-amber-300 text-amber-800 hover:bg-amber-100",
+  },
+} as const;
+
+const props = withDefaults(
+  defineProps<{
+    tone: keyof typeof PALETTES;
+    /** A Material Icons name. */
+    icon: string;
+    title: string;
+    body: string;
+    /** Small print after the body, rendered dimmer. */
+    detail?: string | null;
+    actionLabel: string;
+    /** Disables the action and spins its icon. */
+    busy?: boolean;
+    testid: string;
+    actionTestid: string;
+  }>(),
+  { detail: null, busy: false },
+);
+
+const emit = defineEmits<{ action: [] }>();
+
+const palette = computed(() => PALETTES[props.tone]);
+</script>