@@ -26,6 +26,7 @@ import {
   SettingsEnvironmentFilterHeader,
 } from "./components/SettingsEnvironmentFilterHeader";
 import { BranchNamingSettings } from "./components/BranchNamingSettings";
+import { DatabaseStorageNotice } from "./components/DatabaseStorageNotice";
 import { SettingsChoiceRow } from "./components/SettingsChoiceRow";
 import { SettingsSection } from "./components/SettingsSection";
 import { SettingsSwitchRow } from "./components/SettingsSwitchRow";
@@ -428,6 +429,15 @@ function ServerSettingsDetail(props: { readonly page: SettingsPage }) {
 
               {props.page === "maintenance" ? (
                 <>
+                  {!projectSelected &&
+                    selectedTargets
+                      .filter(
+                        (target) =>
+                          target.serverConfig.environment.capabilities.databaseStorage === true,
+                      )
+                      .map((target) => (
+                        <DatabaseStorageNotice key={target.environmentId} target={target} />
+                      ))}
                   {!projectSelected ? (
                     <SettingsSection title="Manage environments">
                       {selectedTargets.map((target) => (
 
@@ -0,0 +1,62 @@
+import { useAtomSet, useAtomValue } from "@effect/atom-react";
+import { shouldRecommendDatabaseCompaction } from "@t3tools/contracts";
+import { AsyncResult } from "effect/reactivity";
+import { View } from "react-native";
+
+import { AppText as Text } from "../../../components/AppText";
+import { copyTextWithHaptic } from "../../../lib/copyTextWithHaptic";
+import { mobilePreferencesAtom, updateMobilePreferencesAtom } from "../../../state/preferences";
+import { serverEnvironment } from "../../../state/server";
+import type { SettingsTarget } from "../settings-environment-filter";
+import { SettingsActionRow } from "./SettingsActionRow";
+import { SettingsSection } from "./SettingsSection";
+
+/** Suggests `t3 doctor` for a database that still holds at least 1 GiB of freed pages. */
+export function DatabaseStorageNotice({ target }: { readonly target: SettingsTarget }) {
+  const result = useAtomValue(
+    serverEnvironment.databaseStorage({ environmentId: target.environmentId, input: {} }),
+  );
+  const preferences = useAtomValue(mobilePreferencesAtom);
+  const updatePreferences = useAtomSet(updateMobilePreferencesAtom);
+  const dismissed =
+    AsyncResult.isSuccess(preferences) &&
+    preferences.value.dismissedDatabaseStorageNotices?.includes(target.environmentId) === true;
+  const status = result._tag === "Success" ? result.value : null;
+  if (dismissed || status === null || !shouldRecommendDatabaseCompaction(status)) return null;
+  const gib = (status.reclaimableBytes / 1024 ** 3).toFixed(1);
+  return (
+    <SettingsSection title={`Reclaim ${gib} GiB on ${target.label}`}>
+      <View className="gap-3 p-4">
+        <Text className="text-sm text-muted-foreground">
+          Old history is cleaned up automatically, but this database still holds the freed space.
+          Run this command on {target.label} to return it to disk; it pauses and restarts the
+          background service. Quit the desktop app first if it hosts this environment.
+        </Text>
+        <Text selectable className="font-mono text-sm text-foreground">
+          {status.compactCommand}
+        </Text>
+      </View>
+      <SettingsActionRow
+        icon="doc.on.doc"
+        label="Copy command"
+        onPress={() => copyTextWithHaptic(status.compactCommand, { target: "command" })}
+      />
+      <SettingsActionRow
+        icon="xmark"
+        label="Dismiss"
+        onPress={() =>
+          updatePreferences({
+            transform: (current) => ({
+              dismissedDatabaseStorageNotices: [
+                ...new Set([
+                  ...(current.dismissedDatabaseStorageNotices ?? []),
+                  target.environmentId,
+                ]),
+              ],
+            }),
+          })
+        }
+      />
+    </SettingsSection>
+  );
+}
@@ -67,6 +67,8 @@ export interface Preferences {
   readonly codeWordBreak?: boolean;
   readonly connectOnboardingOptOutAccounts?: ReadonlyArray<string>;
   readonly collapsedProjectGroups?: readonly string[];
+  /** Environments whose "reclaim database space" notice was dismissed. */
+  readonly dismissedDatabaseStorageNotices?: readonly string[];
   /** What the Return key does in the composer on a hardware keyboard. iOS only. */
   readonly composerEnterBehavior?: ComposerEnterBehavior;
   /**
@@ -150,6 +152,7 @@ function sanitizePreferences(parsed: Preferences): Preferences {
     codeWordBreak?: boolean;
     connectOnboardingOptOutAccounts?: ReadonlyArray<string>;
     collapsedProjectGroups?: readonly string[];
+    dismissedDatabaseStorageNotices?: readonly string[];
     composerEnterBehavior?: ComposerEnterBehavior;
     followUpBehavior?: FollowUpBehavior;
     microphones?: ReadonlyArray<MicrophoneEntry>;
@@ -226,6 +229,11 @@ function sanitizePreferences(parsed: Preferences): Preferences {
       (key): key is string => typeof key === "string",
     );
   }
+  if (Array.isArray(parsed.dismissedDatabaseStorageNotices)) {
+    preferences.dismissedDatabaseStorageNotices = parsed.dismissedDatabaseStorageNotices.filter(
+      (value): value is string => typeof value === "string",
+    );
+  }
   if (parsed.composerEnterBehavior === "send" || parsed.composerEnterBehavior === "newline") {
     preferences.composerEnterBehavior = parsed.composerEnterBehavior;
   }
 
@@ -85,6 +85,7 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.serverUpsertKeybinding]: AuthSettingsWriteScope,
   [WS_METHODS.serverRemoveKeybinding]: AuthSettingsWriteScope,
   [WS_METHODS.serverGetStorageCleanupReport]: AuthOrchestrationReadScope,
+  [WS_METHODS.serverGetDatabaseStorage]: AuthOrchestrationReadScope,
   [WS_METHODS.serverGetSettings]: AuthOrchestrationReadScope,
   [WS_METHODS.serverUpdateSettings]: AuthSettingsWriteScope,
   [WS_METHODS.serverSearchAcpRegistry]: AuthOrchestrationReadScope,
 
@@ -7,6 +7,7 @@ import * as Path from "effect/Path";
 
 import {
   formatCliCommand,
+  resolveHostCliCommand,
   resolveRootCliCommand,
   resolveServerInstallation,
 } from "./invocation.ts";
@@ -179,6 +180,42 @@ it.layer(NodeServices.layer)("root CLI commands", (it) => {
   );
 });
 
+it.layer(NodeServices.layer)("host CLI commands", (it) => {
+  it.effect("renders a PowerShell command line on Windows", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const home = yield* fs.makeTempDirectoryScoped();
+      const shim = path.join(home, "t3.cmd");
+      yield* fs.writeFileString(shim, "@echo off\r\n");
+      const hostCommand = (platform: NodeJS.Platform, env: Record<string, string>) =>
+        resolveHostCliCommand("doctor", ["--base-dir", "C:\\Users\\Jane Doe\\.t3"]).pipe(
+          Effect.provideService(HostProcess.ExecutablePath, "C:\\Program Files\\T3 Code\\t3.exe"),
+          Effect.provideService(HostProcess.Arguments, [
+            "C:\\Program Files\\T3 Code\\t3.exe",
+            "C:\\Program Files\\T3 Code\\resources\\app.asar\\apps\\server\\dist\\bin.mjs",
+          ]),
+          Effect.provideService(HostProcess.IsExecutable, false),
+          Effect.provideService(HostProcess.Platform, platform),
+          Effect.provideService(HostProcess.Environment, { PATH: "", ...env }),
+        );
+      // The desktop shim is called through `&`, and each argument is quoted
+      // the PowerShell way: no POSIX single quotes anywhere.
+      expect((yield* hostCommand("win32", { T3CODE_CLI_PATH: shim })).command).toBe(
+        `& "${shim}" doctor "--base-dir" "C:\\Users\\Jane Doe\\.t3"`,
+      );
+      // Without a launcher, plain `t3` with PowerShell-quoted arguments.
+      expect((yield* hostCommand("win32", {})).command).toBe(
+        't3 doctor "--base-dir" "C:\\Users\\Jane Doe\\.t3"',
+      );
+      // POSIX hosts keep single quotes for the same input.
+      expect((yield* hostCommand("linux", { T3CODE_CLI_PATH: shim })).command).toBe(
+        `${shim} doctor --base-dir 'C:\\Users\\Jane Doe\\.t3'`,
+      );
+    }).pipe(Effect.scoped),
+  );
+});
+
 it.layer(NodeServices.layer)("manual server installation ownership", (it) => {
   it.effect("recognizes runner caches for both script and executable packages", () =>
     Effect.gen(function* () {
 
@@ -147,6 +147,18 @@ export const resolveCliCommand = (subcommand: string) =>
 const shellWord = (value: string) =>
   /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 
+/**
+ * Quotes `value` for PowerShell, the default Windows terminal. Always quoted,
+ * so a path reads the same whether or not it holds a space. Inside double
+ * quotes `"` doubles, and `$` and the backtick are escaped so nothing expands.
+ */
+const powershellWord = (value: string) =>
+  `"${value.replaceAll("`", "``").replaceAll("$", "`$").replaceAll('"', '""')}"`;
+
+/** Quotes a word for the host's shell: POSIX, or PowerShell on Windows. */
+const hostShellWord = (platform: NodeJS.Platform, value: string) =>
+  platform === "win32" ? powershellWord(value) : shellWord(value);
+
 /**
  * The launcher a person can type to run this install when `t3` is not on
  * PATH: the desktop app's `t3` shim, which the app and the shim itself name in
@@ -165,19 +177,26 @@ const resolveInstallLauncher = Effect.gen(function* () {
 });
 
 /**
- * `t3 <subcommand>` for a person to run on this host: `t3` when it is on PATH,
- * the package runner this process came from, or else the absolute path of the
- * launcher for this install, such as the one the desktop app installs.
+ * `t3 <subcommand> <args>` for a person to run on this host: `t3` when it is
+ * on PATH, the package runner this process came from, or else the absolute
+ * path of the launcher for this install, such as the one the desktop app
+ * installs. `args` are quoted for the host's shell: POSIX, or PowerShell on
+ * Windows.
  */
-const resolveHostCliCommand = (subcommand: string) =>
+export const resolveHostCliCommand = (subcommand: string, args: ReadonlyArray<string> = []) =>
   Effect.gen(function* () {
+    const platform = yield* HostProcess.Platform;
+    const withArgs = (prefix: string) =>
+      [prefix, ...args.map((arg) => hostShellWord(platform, arg))].join(" ");
     const command = yield* resolveCliCommand(subcommand);
-    if (command !== `t3 ${subcommand}`) return { command, launcher: false };
-    if (yield* isCommandAvailable("t3")) return { command, launcher: false };
+    if (command !== `t3 ${subcommand}`) return { command: withArgs(command), launcher: false };
+    if (yield* isCommandAvailable("t3")) return { command: withArgs(command), launcher: false };
     const launcher = yield* resolveInstallLauncher;
-    return Option.isSome(launcher)
-      ? { command: `${shellWord(launcher.value)} ${subcommand}`, launcher: true }
-      : { command, launcher: false };
+    if (Option.isNone(launcher)) return { command: withArgs(command), launcher: false };
+    // PowerShell runs a quoted path only through the call operator.
+    const quoted = hostShellWord(platform, launcher.value);
+    const call = platform === "win32" ? `& ${quoted}` : quoted;
+    return { command: withArgs(`${call} ${subcommand}`), launcher: true };
   });
 
 /**
 
@@ -229,6 +229,7 @@ export const make = Effect.gen(function* () {
       threadAutoSettlement: true,
       storageCleanup: true,
       storageCleanupRun: true,
+      databaseStorage: true,
       otlpEndpointCheck: true,
       projectWorktreeCleanup: true,
       worktreesDirectory: true,
 
@@ -57,6 +57,7 @@ const RPC_AGGREGATES = {
   [WS_METHODS.serverRemoveKeybinding]: "server",
   [WS_METHODS.serverRunStorageCleanup]: "server",
   [WS_METHODS.serverGetStorageCleanupReport]: "server",
+  [WS_METHODS.serverGetDatabaseStorage]: "server",
   [WS_METHODS.serverGetSettings]: "server",
   [WS_METHODS.serverUpdateSettings]: "server",
   [WS_METHODS.serverSearchAcpRegistry]: "server",
 
@@ -1,8 +1,10 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as SqlClient from "effect/sql/SqlClient";
 
+import * as ServerConfig from "../config.ts";
 import * as EventStore from "../orchestration-v2/EventStore.ts";
 import * as ProjectionMaintenance from "../orchestration-v2/ProjectionMaintenance.ts";
 import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
@@ -37,6 +39,8 @@ it.effect("a new database returns freed pages online without losing data", () =>
         Layer.provide(ProjectionMaintenance.layer),
         Layer.provide(Layer.merge(EventStore.layer, ProjectionStore.layer)),
         Layer.provideMerge(Sqlite.layerMemory),
+        Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "database-storage-" })),
+        Layer.provide(NodeServices.layer),
       ),
     ),
   ),
 
@@ -1,9 +1,16 @@
+import type { DatabaseStorageStatus } from "@t3tools/contracts";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
 import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
 import * as SqlClient from "effect/sql/SqlClient";
 
+import { resolveHostCliCommand } from "../cli/invocation.ts";
+import * as ServerConfig from "../config.ts";
 import * as ProjectionMaintenance from "../orchestration-v2/ProjectionMaintenance.ts";
 import { forkParked } from "../serverActivation.ts";
 
@@ -15,6 +22,8 @@ export class DatabaseStorage extends Context.Service<
   {
     /** Return free pages to the filesystem on databases with incremental auto_vacuum. */
     readonly reclaim: Effect.Effect<void>;
+    /** Current file accounting, re-published after each maintenance pass. Null until first read. */
+    readonly status: Stream.Stream<DatabaseStorageStatus | null>;
   }
 >()("t3/persistence/DatabaseStorage") {}
 
@@ -29,6 +38,42 @@ export const layer = Layer.effect(
   Effect.gen(function* () {
     const sql = yield* SqlClient.SqlClient;
     const maintenance = yield* ProjectionMaintenance.ProjectionMaintenanceV2;
+    const config = yield* ServerConfig.ServerConfig;
+    const path = yield* Path.Path;
+    const statusRef = yield* SubscriptionRef.make<DatabaseStorageStatus | null>(null);
+
+    // The notice shows this verbatim; quote for the host's shell. Desktop
+    // installs have no `t3` on PATH, so the command names their launcher.
+    const { command: compactCommand } = yield* resolveHostCliCommand("doctor", [
+      "--base-dir",
+      config.baseDir,
+    ]);
+    // `t3 doctor --base-dir` repairs <baseDir>/userdata. A dev server without
+    // an explicit home keeps its state in <baseDir>/dev instead, so there the
+    // command would target the live install; publish no status at all.
+    const doctorTargetsThisDatabase =
+      path.resolve(config.dbPath) ===
+      path.resolve(config.baseDir, "userdata", path.basename(config.dbPath));
+    const publishStatus = Effect.gen(function* () {
+      if (!doctorTargetsThisDatabase) return;
+      const pages = yield* sql<{ readonly page_count: number }>`PRAGMA page_count`;
+      const free = yield* sql<{ readonly freelist_count: number }>`PRAGMA freelist_count`;
+      const size = yield* sql<{ readonly page_size: number }>`PRAGMA page_size`;
+      const mode = yield* sql<{ readonly auto_vacuum: number }>`PRAGMA auto_vacuum`;
+      const pageSize = size[0]?.page_size ?? 0;
+      const next: DatabaseStorageStatus = {
+        databaseBytes: (pages[0]?.page_count ?? 0) * pageSize,
+        reclaimableBytes: (free[0]?.freelist_count ?? 0) * pageSize,
+        incrementalVacuumEnabled: mode[0]?.auto_vacuum === 2,
+        compactCommand,
+      };
+      // Every set reaches each open Storage page; most passes change nothing.
+      if (!Equal.equals(yield* SubscriptionRef.get(statusRef), next)) {
+        yield* SubscriptionRef.set(statusRef, next);
+      }
+    }).pipe(
+      Effect.catch((cause) => Effect.logWarning("Database storage inspection failed", { cause })),
+    );
 
     const reclaim = Effect.gen(function* () {
       const mode = yield* sql<{ readonly auto_vacuum: number }>`PRAGMA auto_vacuum`;
@@ -59,15 +104,20 @@ export const layer = Layer.effect(
 
     yield* forkParked(
       Effect.sleep("1 minute").pipe(
-        Effect.andThen(compact.pipe(Effect.repeat(Schedule.spaced("6 hours")))),
+        Effect.andThen(
+          compact.pipe(Effect.andThen(publishStatus), Effect.repeat(Schedule.spaced("6 hours"))),
+        ),
       ),
     );
     yield* forkParked(
-      Effect.sleep("1 minute").pipe(
-        Effect.andThen(reclaim.pipe(Effect.repeat(Schedule.spaced("1 minute")))),
+      publishStatus.pipe(
+        Effect.andThen(Effect.sleep("1 minute")),
+        Effect.andThen(
+          reclaim.pipe(Effect.andThen(publishStatus), Effect.repeat(Schedule.spaced("1 minute"))),
+        ),
       ),
     );
 
-    return DatabaseStorage.of({ reclaim });
+    return DatabaseStorage.of({ reclaim, status: SubscriptionRef.changes(statusRef) });
   }),
 );