feat(session): keep transcripts for 365 days by default

Transcripts now default to a 365-day retention and can be changed from
Settings > General, where a change previews how many files the new window
removes and requires confirmation before anything is deleted. Plans, file
history, debug logs, pastes and agent worktrees keep the previous 30-day
window instead of inheriting the transcript setting.

Also cleans subagent transcripts together with their parent session, and
restricts the bulk cleanup endpoint to the desktop process token so an H5
token cannot wipe every transcript in one request.

Author: NanmiCoder

desktop/src/__tests__/generalSettings.test.tsx

@@ -262,6 +262,7 @@ describe('Settings > General tab', () => {
         aiRequestTimeoutMs: 120_000,
         proxy: { mode: 'direct', url: '' },
       },
+      cleanupPeriodDays: null,
       h5Access: {
         enabled: false,
         token: null,
@@ -333,6 +334,9 @@ describe('Settings > General tab', () => {
       setNetwork: vi.fn().mockImplementation(async (network) => {
         useSettingsStore.setState({ network })
       }),
+      setCleanupPeriodDays: vi.fn().mockImplementation(async (days: number) => {
+        useSettingsStore.setState({ cleanupPeriodDays: days })
+      }),
       appMode: {
         mode: 'default',
         portableDir: null,
@@ -657,6 +661,280 @@ describe('Settings > General tab', () => {
     expect(saveButton).not.toBeDisabled()
   })
 
+  it('previews session cleanup and only deletes after confirmation', async () => {
+    const cleanupSessions = vi
+      .spyOn(settingsApi, 'cleanupSessions')
+      .mockImplementation(async (days, dryRun = false) => ({
+        ok: true,
+        days,
+        dryRun,
+        files: 7,
+        errors: 0,
+      }))
+
+    try {
+      render(<Settings />)
+      fireEvent.click(screen.getByText('General'))
+
+      const input = screen.getByLabelText('Keep session history for')
+      expect(input).toHaveValue(365)
+
+      const section = screen.getByRole('heading', { name: 'Session History' })
+        .parentElement as HTMLElement
+      const saveButton = within(section).getByRole('button', { name: 'Save' })
+      expect(saveButton).toBeDisabled()
+
+      fireEvent.change(input, { target: { value: '90' } })
+      expect(saveButton).not.toBeDisabled()
+
+      await act(async () => {
+        fireEvent.click(saveButton)
+      })
+
+      expect(cleanupSessions).toHaveBeenCalledWith(90, true)
+      expect(useSettingsStore.getState().setCleanupPeriodDays).not.toHaveBeenCalled()
+
+      const dialog = screen.getByRole('dialog', { name: 'Change session history retention?' })
+      expect(within(dialog).getByText('7 files currently match this cutoff.')).toBeInTheDocument()
+      expect(
+        within(dialog).getByText(/Sessions older than 90 days will be permanently deleted/),
+      ).toBeInTheDocument()
+
+      await act(async () => {
+        fireEvent.click(within(dialog).getByRole('button', { name: 'Delete and save' }))
+      })
+
+      expect(useSettingsStore.getState().setCleanupPeriodDays).toHaveBeenCalledWith(90)
+      expect(cleanupSessions).toHaveBeenLastCalledWith(90)
+      expect(useSettingsStore.getState().cleanupPeriodDays).toBe(90)
+      expect(
+        screen.queryByRole('dialog', { name: 'Change session history retention?' }),
+      ).not.toBeInTheDocument()
+      expect(
+        useUIStore.getState().toasts[useUIStore.getState().toasts.length - 1],
+      ).toMatchObject({
+        type: 'success',
+        message: 'Retention updated. 7 old session files removed.',
+      })
+    } finally {
+      cleanupSessions.mockRestore()
+    }
+  })
+
+  it('cancelling the retention confirmation keeps the stored value', async () => {
+    const cleanupSessions = vi.spyOn(settingsApi, 'cleanupSessions').mockResolvedValue({
+      ok: true,
+      days: 0,
+      dryRun: true,
+      files: 3,
+      errors: 0,
+    })
+
+    try {
+      render(<Settings />)
+      fireEvent.click(screen.getByText('General'))
+
+      const input = screen.getByLabelText('Keep session history for')
+      fireEvent.change(input, { target: { value: '0' } })
+
+      const section = screen.getByRole('heading', { name: 'Session History' })
+        .parentElement as HTMLElement
+      await act(async () => {
+        fireEvent.click(within(section).getByRole('button', { name: 'Save' }))
+      })
+
+      const dialog = screen.getByRole('dialog', { name: 'Change session history retention?' })
+      expect(
+        within(dialog).getByText(/stops recording new session content and permanently deletes/),
+      ).toBeInTheDocument()
+
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Cancel' }))
+
+      expect(useSettingsStore.getState().setCleanupPeriodDays).not.toHaveBeenCalled()
+      expect(cleanupSessions).toHaveBeenCalledTimes(1)
+      expect(input).toHaveValue(0)
+    } finally {
+      cleanupSessions.mockRestore()
+    }
+  })
+
+  it('surfaces a failed cleanup inside the dialog so the user can retry', async () => {
+    const cleanupSessions = vi
+      .spyOn(settingsApi, 'cleanupSessions')
+      .mockResolvedValueOnce({ ok: true, days: 90, dryRun: true, files: 4, errors: 0 })
+      .mockRejectedValueOnce(new Error('disk offline'))
+
+    try {
+      render(<Settings />)
+      fireEvent.click(screen.getByText('General'))
+      fireEvent.change(screen.getByLabelText('Keep session history for'), {
+        target: { value: '90' },
+      })
+
+      const section = screen.getByRole('heading', { name: 'Session History' })
+        .parentElement as HTMLElement
+      await act(async () => {
+        fireEvent.click(within(section).getByRole('button', { name: 'Save' }))
+      })
+
+      const dialog = screen.getByRole('dialog', { name: 'Change session history retention?' })
+      await act(async () => {
+        fireEvent.click(within(dialog).getByRole('button', { name: 'Delete and save' }))
+      })
+
+      // The error must be visible inside the modal (the card behind it is
+      // covered) and the dialog must stay open so confirming again retries.
+      expect(within(dialog).getByText('disk offline')).toBeInTheDocument()
+      expect(
+        screen.getByRole('dialog', { name: 'Change session history retention?' }),
+      ).toBeInTheDocument()
+    } finally {
+      cleanupSessions.mockRestore()
+    }
+  })
+
+  it('opens the confirmation only after the impact count is known', async () => {
+    let resolvePreview!: (value: Awaited<ReturnType<typeof settingsApi.cleanupSessions>>) => void
+    const previewPromise = new Promise<Awaited<ReturnType<typeof settingsApi.cleanupSessions>>>(
+      (resolve) => {
+        resolvePreview = resolve
+      },
+    )
+    const cleanupSessions = vi.spyOn(settingsApi, 'cleanupSessions').mockReturnValue(previewPromise)
+
+    try {
+      render(<Settings />)
+      fireEvent.click(screen.getByText('General'))
+      fireEvent.change(screen.getByLabelText('Keep session history for'), {
+        target: { value: '90' },
+      })
+
+      const section = screen.getByRole('heading', { name: 'Session History' })
+        .parentElement as HTMLElement
+      const saveButton = within(section).getByRole('button', { name: 'Save' })
+      fireEvent.click(saveButton)
+
+      // While the dry-run is in flight there is nothing to confirm yet.
+      expect(saveButton).toBeDisabled()
+      expect(
+        screen.queryByRole('dialog', { name: 'Change session history retention?' }),
+      ).not.toBeInTheDocument()
+
+      await act(async () => {
+        resolvePreview({ ok: true, days: 90, dryRun: true, files: 5, errors: 0 })
+      })
+
+      const dialog = screen.getByRole('dialog', { name: 'Change session history retention?' })
+      expect(within(dialog).getByText('5 files currently match this cutoff.')).toBeInTheDocument()
+      expect(useSettingsStore.getState().setCleanupPeriodDays).not.toHaveBeenCalled()
+    } finally {
+      cleanupSessions.mockRestore()
+    }
+  })
+
+  it('reports files it could not remove instead of a clean success', async () => {
+    const cleanupSessions = vi
+      .spyOn(settingsApi, 'cleanupSessions')
+      .mockImplementation(async (days, dryRun = false) => ({
+        ok: true,
+        days,
+        dryRun,
+        files: 6,
+        errors: dryRun ? 0 : 2,
+      }))
+
+    try {
+      render(<Settings />)
+      fireEvent.click(screen.getByText('General'))
+      fireEvent.change(screen.getByLabelText('Keep session history for'), {
+        target: { value: '90' },
+      })
+
+      const section = screen.getByRole('heading', { name: 'Session History' })
+        .parentElement as HTMLElement
+      await act(async () => {
+        fireEvent.click(within(section).getByRole('button', { name: 'Save' }))
+      })
+
+      const dialog = screen.getByRole('dialog', { name: 'Change session history retention?' })
+      await act(async () => {
+        fireEvent.click(within(dialog).getByRole('button', { name: 'Delete and save' }))
+      })
+
+      expect(
+        useUIStore.getState().toasts[useUIStore.getState().toasts.length - 1],
+      ).toMatchObject({
+        type: 'success',
+        message: 'Retention updated. 6 old session files removed, 2 could not be removed.',
+      })
+    } finally {
+      cleanupSessions.mockRestore()
+    }
+  })
+
+  it('confirms the value the dialog was opened with even if the store moves underneath', async () => {
+    // A failed save rolls the store back and the effect then resets the input
+    // behind the modal. The dialog must stay pinned to what the user saw, or
+    // the retry would silently apply the rolled-back value instead.
+    const cleanupSessions = vi
+      .spyOn(settingsApi, 'cleanupSessions')
+      .mockImplementation(async (days, dryRun = false) => ({
+        ok: true,
+        days,
+        dryRun,
+        files: 3,
+        errors: 0,
+      }))
+
+    try {
+      render(<Settings />)
+      fireEvent.click(screen.getByText('General'))
+      fireEvent.change(screen.getByLabelText('Keep session history for'), {
+        target: { value: '90' },
+      })
+
+      const section = screen.getByRole('heading', { name: 'Session History' })
+        .parentElement as HTMLElement
+      await act(async () => {
+        fireEvent.click(within(section).getByRole('button', { name: 'Save' }))
+      })
+
+      const dialog = screen.getByRole('dialog', { name: 'Change session history retention?' })
+      expect(
+        within(dialog).getByText(/Sessions older than 90 days will be permanently deleted/),
+      ).toBeInTheDocument()
+
+      await act(async () => {
+        useSettingsStore.setState({ cleanupPeriodDays: 365 })
+      })
+      // Precondition for the regression: the input behind the modal moved.
+      expect(screen.getByLabelText('Keep session history for')).toHaveValue(365)
+
+      await act(async () => {
+        fireEvent.click(within(dialog).getByRole('button', { name: 'Delete and save' }))
+      })
+
+      expect(useSettingsStore.getState().setCleanupPeriodDays).toHaveBeenLastCalledWith(90)
+      expect(cleanupSessions).toHaveBeenLastCalledWith(90)
+    } finally {
+      cleanupSessions.mockRestore()
+    }
+  })
+
+  it('hides the retention controls on a touch-H5 phone browser', () => {
+    document.documentElement.setAttribute('data-touch-h5', 'true')
+    try {
+      render(<Settings />)
+      fireEvent.click(screen.getByText('General'))
+
+      expect(
+        screen.queryByRole('heading', { name: 'Session History' }),
+      ).not.toBeInTheDocument()
+    } finally {
+      document.documentElement.removeAttribute('data-touch-h5')
+    }
+  })
+
   it('keeps data storage at the bottom of General settings', () => {
     render(<Settings />)
 
@@ -1725,8 +2003,9 @@ describe('Settings > General tab', () => {
     fireEvent.change(screen.getByLabelText('Tavily API key'), {
       target: { value: 'tvly-test-key' },
     })
-    const saveButtons = screen.getAllByRole('button', { name: 'Save' })
-    fireEvent.click(saveButtons[saveButtons.length - 1]!)
+    const webSearchSection = screen.getByRole('heading', { name: 'WebSearch' })
+      .parentElement as HTMLElement
+    fireEvent.click(within(webSearchSection).getByRole('button', { name: 'Save' }))
 
     expect(useSettingsStore.getState().setWebSearch).toHaveBeenCalledWith({
       mode: 'tavily',

desktop/src/api/settings.ts

@@ -1,5 +1,10 @@
 import { api } from './client'
-import type { OutputStylesResponse, PermissionMode, UserSettings } from '../types/settings'
+import type {
+  OutputStylesResponse,
+  PermissionMode,
+  SessionCleanupResult,
+  UserSettings,
+} from '../types/settings'
 
 export type CliLauncherStatus = {
   supported: boolean
@@ -52,4 +57,16 @@ export const settingsApi = {
   getCliLauncherStatus() {
     return api.get<CliLauncherStatus>('/api/settings/cli-launcher')
   },
+
+  /**
+   * Delete transcripts older than `days`, or preview how many files that would
+   * remove when `dryRun` is set. Mirrors `cleanupPeriodDays` semantics: 0 wipes
+   * every transcript and stops future persistence.
+   */
+  cleanupSessions(days: number, dryRun = false) {
+    return api.post<SessionCleanupResult>('/api/settings/session-cleanup', {
+      days,
+      dryRun,
+    })
+  },
 }

desktop/src/i18n/locales/en.ts

@@ -1549,6 +1549,24 @@ Row 9, all 8 cells: continuing from straight down, turning left through lower-le
   // Settings > General - Storage
   'settings.general.modeSwitchTitle': 'Switch data storage location?',
   'settings.general.modeSwitchConfirm': 'Save and Restart',
+  'settings.general.sessionRetentionTitle': 'Session History',
+  'settings.general.sessionRetentionDescription': 'How long transcripts are kept on this device. Lowering the value deletes older sessions right away, so it asks for confirmation first.',
+  'settings.general.sessionRetentionLabel': 'Keep session history for',
+  'settings.general.sessionRetentionCurrent': 'Current: {days} days',
+  'settings.general.sessionRetentionCurrentOff': 'Current: not saved',
+  'settings.general.sessionRetentionUnit': 'days',
+  'settings.general.sessionRetentionHint': 'Default is 365 days. Setting this to 0 stops recording session content and deletes every existing transcript.',
+  'settings.general.sessionRetentionRequired': 'Enter a number of days.',
+  'settings.general.sessionRetentionRange': 'Enter a whole number from 0 to {max}.',
+  'settings.general.sessionRetentionSave': 'Save',
+  'settings.general.sessionRetentionSaved': 'Retention updated. {count} old session files removed.',
+  'settings.general.sessionRetentionSavedPartial': 'Retention updated. {count} old session files removed, {errors} could not be removed.',
+  'settings.general.sessionRetentionConfirmTitle': 'Change session history retention?',
+  'settings.general.sessionRetentionConfirmDelete': 'Sessions older than {days} days will be permanently deleted. This cannot be undone.',
+  'settings.general.sessionRetentionConfirmDisable': 'Setting this to 0 stops recording new session content and permanently deletes every existing transcript. This cannot be undone.',
+  'settings.general.sessionRetentionPreview': '{count} files currently match this cutoff.',
+  'settings.general.sessionRetentionPreviewUnavailable': 'Could not count matching files. You can still confirm.',
+  'settings.general.sessionRetentionConfirmAction': 'Delete and save',
   'settings.general.storageTitle': 'Data Storage Location',
   'settings.general.storageDescription': 'Advanced, low-frequency setting. After switching, sessions, Skills, MCP, plugins, provider settings, tasks, and caches are read from the new directory.',
   'settings.general.storageSystemTitle': 'Use system directory',

desktop/src/i18n/locales/jp.ts

@@ -1551,6 +1551,24 @@ export const jp: Record<TranslationKey, string> = {
   // Settings > General - Storage
   'settings.general.modeSwitchTitle': 'データ保存場所を切り替えますか？',
   'settings.general.modeSwitchConfirm': '保存して再起動',
+  'settings.general.sessionRetentionTitle': 'セッション履歴',
+  'settings.general.sessionRetentionDescription': 'セッション記録をこの端末に保持する期間です。値を小さくすると古い記録がすぐに削除されるため、確認を求めます。',
+  'settings.general.sessionRetentionLabel': 'セッション履歴の保持期間',
+  'settings.general.sessionRetentionCurrent': '現在：{days} 日',
+  'settings.general.sessionRetentionCurrentOff': '現在：記録を保存しない',
+  'settings.general.sessionRetentionUnit': '日',
+  'settings.general.sessionRetentionHint': '既定は 365 日です。0 にするとセッション内容を記録しなくなり、既存の記録もすべて削除します。',
+  'settings.general.sessionRetentionRequired': '日数を入力してください。',
+  'settings.general.sessionRetentionRange': '0 から {max} までの整数を入力してください。',
+  'settings.general.sessionRetentionSave': '保存',
+  'settings.general.sessionRetentionSaved': '保持期間を更新し、期限切れのセッションファイルを {count} 件削除しました。',
+  'settings.general.sessionRetentionSavedPartial': '保持期間を更新しました。期限切れのセッションファイルを {count} 件削除し、{errors} 件は削除できませんでした。',
+  'settings.general.sessionRetentionConfirmTitle': 'セッション履歴の保持期間を変更しますか？',
+  'settings.general.sessionRetentionConfirmDelete': '{days} 日より古いセッション記録を完全に削除します。元に戻せません。',
+  'settings.general.sessionRetentionConfirmDisable': '0 にすると新しいセッション内容を記録しなくなり、既存の記録もすべて完全に削除します。元に戻せません。',
+  'settings.general.sessionRetentionPreview': 'この設定では現在 {count} 件のファイルが削除されます。',
+  'settings.general.sessionRetentionPreviewUnavailable': '集計に失敗しました。そのまま続行できます。',
+  'settings.general.sessionRetentionConfirmAction': '削除して保存',
   'settings.general.storageTitle': 'データ保存場所',
   'settings.general.storageDescription': '高度で使用頻度の低い設定です。切り替え後は、セッション、スキル、MCP、プラグイン、プロバイダー設定、タスク、キャッシュが新しいディレクトリから読み込まれます。',
   'settings.general.storageSystemTitle': 'システムディレクトリを使用',