feat(sync): drop quiescence guard in favor of live WAL-based sync

- Remove `canAutoSync` dep from scheduler; auto-sync now runs during playback/stats - Sync window always passes `--force`; WAL snapshots and transactional merges handle concurrent writers - Update docs to clarify live vs cold-start sync modes
feat(sync): emit structured remote merge-summary event
2026-07-27 04:49:49 -07:00 · 2026-07-13 03:29:07 -07:00 · 2026-07-13 02:40:59 -07:00 · 2026-07-13 00:09:11 -07:00 · 2026-07-12 23:59:20 -07:00 · 2026-07-12 23:22:44 -07:00
62 changed files with 1419 additions and 1141 deletions
@@ -3,7 +3,7 @@
 ## Unreleased

 ### Added
- Stats Sync Without the Launcher: The stats sync engine now runs only inside the app. The sync window and the `subminer sync` command both delegate to `SubMiner --sync-cli` (headless, works over SSH with no display), so neither machine needs bun or the command-line launcher — a remote machine only needs SubMiner itself, found automatically as the app binary or via the launcher proxy.
+- Stats Sync Without the Launcher: The stats sync engine now runs only inside the app. The sync window and the `subminer sync` command both delegate to `SubMiner --sync-cli` (headless, works over SSH with no display), so neither machine needs bun or the command-line launcher. A remote machine only needs SubMiner itself, found automatically as the app binary or via the launcher proxy.
 - Stats Sync With Windows Remotes: Sync now detects the remote shell (POSIX, cmd, or PowerShell) and manages remote temp files through SubMiner itself (`sync --make-temp`/`--remove-temp`) instead of `mktemp`/`rm`, so a Windows machine with the built-in OpenSSH Server works as a sync remote; SubMiner is found in its default Windows install location automatically.

 ## v0.18.0 (2026-07-10)
@@ -0,0 +1,6 @@
+type: fixed
+area: sync
+
+- Fixed the app staying alive in the background after closing a standalone Sync window (`subminer sync --ui`) on macOS. The quit re-issued after async will-quit cleanup was dropped by Electron when the cleanup settled within the same tick as the will-quit dispatch; the re-quit now runs on a fresh macrotask, and the standalone Sync window close path uses the same forced-exit fallback as SIGTERM. Windows opened from the tray menu of a running app are unaffected: closing them still leaves the app running.
+- Fixed a sync run hanging when the sync child exited without emitting a terminal result: the run waited on `close`, which a descendant holding the inherited stdio pipes can delay indefinitely, stalling the quit-time sync shutdown. Cancelling now settles the run as soon as the child has exited, and an exit with no result settles after a bounded stdout drain window.
+- Fixed sync progress and error text being corrupted when a multibyte character (e.g. a Japanese media title) straddled a chunk boundary in the sync child's output.
@@ -1,5 +1,5 @@
 type: added
 area: sync

- Added a sync window (`subminer sync --ui`, or **Sync Stats & History** in the tray menu) for cross-machine immersion sync: saved devices with per-host direction (two-way/push/pull) and remove, one-click sync with live stage-by-stage progress and merge summaries, connection testing for first-time setup, cancellable runs with a one-click `--force` retry when the running-app guard trips, and manual database snapshots (create/merge/reveal/delete, stored in `/tmp/subminer-db-snapshots/` by default). Hosts with auto-sync enabled are synced in the background on a configurable interval while no mpv session or stats server is writing the database, with results reported as overlay notifications. Hosts synced from the CLI are remembered in `<config dir>/sync-hosts.json` and show up in the window automatically. When launched with `subminer sync --ui`, closing the window also exits the attached CLI process cleanly.
- Added `subminer sync <host> --check` to test the SSH connection and remote launcher availability without syncing, and `subminer sync --json` for machine-readable NDJSON progress output (the protocol the sync window consumes).
+- Added a sync window (`subminer sync --ui`, or **Sync Stats & History** in the tray menu) for cross-machine immersion sync: saved devices with per-host direction (two-way/push/pull) and remove, one-click sync with live stage-by-stage progress and separate merge summaries for this machine and the remote device, connection testing for first-time setup, cancellable live syncs while the app, stats server, or playback is active, and manual database snapshots (create/merge/reveal/delete, stored in `/tmp/subminer-db-snapshots/` by default). Live sync uses a consistent WAL snapshot and transactional merge, and excludes unfinished sessions until a later sync sees them finalized. Hosts with auto-sync enabled are synced in the background on a configurable interval, including during playback, with results reported as overlay notifications. Hosts synced from the CLI are remembered in `<config dir>/sync-hosts.json` and show up in the window automatically. `subminer sync --ui` launches silently in the background and returns the shell immediately; closing that standalone Sync window shuts down the app.
+- Added `subminer sync <host> --check` to test the SSH connection and remote launcher availability without syncing, using bounded noninteractive probes and settling when the check process exits even if an inherited output pipe remains open, without dropping terminal progress that races process exit. Linux AppImage sync commands clear inherited GUI startup argument transport before launching the bundled engine, then exit directly, so sync window checks and remote snapshots never initialize the GUI or require a display server. Added `subminer sync --json` for machine-readable NDJSON progress output (the protocol the sync window consumes).
@@ -3,7 +3,7 @@
 ## Unreleased

 **Added**
- Stats Sync Without the Launcher: The stats sync engine now runs only inside the app. The sync window and the `subminer sync` command both delegate to `SubMiner --sync-cli` (headless, works over SSH with no display), so neither machine needs bun or the command-line launcher — a remote machine only needs SubMiner itself, found automatically as the app binary or via the launcher proxy.
+- Stats Sync Without the Launcher: The stats sync engine now runs only inside the app. The sync window and the `subminer sync` command both delegate to `SubMiner --sync-cli` (headless, works over SSH with no display), so neither machine needs bun or the command-line launcher. A remote machine only needs SubMiner itself, found automatically as the app binary or via the launcher proxy.
 - Stats Sync With Windows Remotes: Sync now detects the remote shell (POSIX, cmd, or PowerShell) and manages remote temp files through SubMiner itself (`sync --make-temp`/`--remove-temp`) instead of `mktemp`/`rm`, so a Windows machine with the built-in OpenSSH Server works as a sync remote; SubMiner is found in its default Windows install location automatically.

 ## v0.18.0 (2026-07-10)
@@ -81,7 +81,7 @@ Series whose directories are not currently accessible (e.g. an unmounted network

 ## Sync Between Machines

-`subminer sync <host>` merges immersion stats and watch history between two machines over SSH, so both end up with the union of sessions, lifetime totals, vocabulary counts, daily/monthly charts, and `--history` entries. `<host>` is anything `ssh` accepts (`user@hostname` or an ssh config alias); SubMiner must be installed on both machines at the same version. The sync engine runs only inside the app (`SubMiner --sync-cli sync ...`): the sync window spawns it that way, `subminer sync` is a thin proxy that forwards to the installed app, and the remote side is found automatically whether it has the launcher or just the app — so the command-line launcher is optional everywhere.
+`subminer sync <host>` merges immersion stats and watch history between two machines over SSH, so both end up with the union of sessions, lifetime totals, vocabulary counts, daily/monthly charts, and `--history` entries. `<host>` is anything `ssh` accepts (`user@hostname` or an ssh config alias); SubMiner must be installed on both machines at the same version. The sync engine runs only inside the app (`SubMiner --sync-cli sync ...`): the sync window spawns it that way, `subminer sync` is a thin proxy that forwards to the installed app, and the remote side is found automatically whether it has the launcher or just the app. The command-line launcher is optional everywhere.

 ```bash
 subminer sync macbook                  # two-way sync with the host "macbook"
@@ -93,11 +93,11 @@ subminer sync macbook --check          # test SSH + remote SubMiner without sync
 subminer sync --ui                     # open the sync window (also in the tray menu)
 ```

-How it works: each side takes a consistent snapshot of its database (`VACUUM INTO`), the snapshots are exchanged over `scp`, and each machine merges the other's snapshot into its own database. The merge is an insert-only union keyed on stable identifiers (session UUIDs, video keys, series title keys, word/kanji identity), so it is safe to re-run at any time — syncing twice changes nothing, and nothing is ever overwritten or summed twice. Lifetime totals and rollup charts are updated incrementally, so history older than the session retention window is preserved on both sides.
+How it works: each side takes a consistent snapshot of its database (`VACUUM INTO`), the snapshots are exchanged over `scp`, and each machine merges the other's snapshot into its own database. The merge is an insert-only union keyed on stable identifiers (session UUIDs, video keys, series title keys, word/kanji identity), so it is safe to re-run at any time. Syncing twice changes nothing, and nothing is ever overwritten or summed twice. Lifetime totals and rollup charts are updated incrementally, so history older than the session retention window is preserved on both sides.

 For a one-way transfer, `--push` snapshots the local database and merges it into the host without changing the local database. `--pull` snapshots the host and merges it into the local database without changing the host. These modes add missing data; they do not delete destination-only data or make the destination an exact mirror.

-Close SubMiner (and stop the background stats daemon, `subminer stats -s`) on both machines before syncing; the command refuses to run while a SubMiner process may be writing the database (`--force` overrides). The mpv safety check requires a live socket connection, so a stale socket file left after mpv exits does not block sync. Both machines must be on the same SubMiner version — the sync aborts on a stats schema mismatch.
+Command-line sync defaults to a cold-start safety check: close SubMiner (and stop the background stats daemon with `subminer stats -s`) on both machines before running it, or pass `--force`. Syncs started from the Sync window use live mode automatically, including scheduled auto-syncs while SubMiner or playback is active. SQLite WAL provides a consistent snapshot, the transactional merge serializes with live writes, and each machine's unfinished session is excluded from the transfer; that session syncs normally after it finishes. The mpv safety check requires a live socket connection, so a stale socket file left after mpv exits does not block command-line sync. Both machines must be on the same SubMiner version; otherwise, the sync aborts on a stats schema mismatch.

 On the remote, sync looks for the `subminer` launcher first (PATH and `~/.local/bin`), then the app binary in `--sync-cli` mode (`SubMiner` on PATH, then the standard macOS `/Applications` and `~/Applications` installs), checking standard SubMiner and Bun locations (`~/.local/bin`, `~/.bun/bin`, Homebrew, `/usr/local/bin`, `/usr/bin`, and `/bin`) even when the non-interactive SSH shell omits them from `PATH`. An AppImage in a custom location can be addressed with `--remote-cmd /path/to/SubMiner.AppImage` (or symlink it as `SubMiner` somewhere on the remote PATH).

@@ -110,22 +110,22 @@ subminer sync --snapshot /tmp/stats.sqlite   # write a consistent snapshot of th
 subminer sync --merge /tmp/stats.sqlite      # merge a snapshot file into the local database
 ```

-Unfinished sessions (a crash mid-playback) are skipped until the app finalizes them; they sync on the next run. Word/kanji "known" state from Anki is not part of the database and does not sync — each machine derives it from its own Anki collection.
+Unfinished sessions (a crash mid-playback) are skipped until the app finalizes them; they sync on the next run. Word/kanji "known" state from Anki is not part of the database and does not sync. Each machine derives it from its own Anki collection.

 `subminer sync <host> --check` verifies a host without touching any data: it probes the SSH connection, locates SubMiner on the remote (launcher or app binary), and reports its version. `--json` switches any sync mode to machine-readable NDJSON progress output (this is what the sync window consumes).

-`sync --make-temp` creates a restricted temporary directory and prints its path; `sync --remove-temp <dir>` removes one created by that command. They are internal SSH transfer helpers, exposed for compatibility but normally invoked only by sync itself. `SubMiner --sync-cli sync ...` is the packaged app's headless compatibility entrypoint; use `SubMiner --sync-cli --help` for its sync-specific help. The `subminer sync` launcher command selects this entrypoint automatically.
+`sync --make-temp` creates a restricted temporary directory and prints its path; `sync --remove-temp <dir>` removes one created by that command. They are internal SSH transfer helpers, exposed for compatibility but normally invoked only by sync itself. `SubMiner --sync-cli sync ...` is the packaged app's headless compatibility entrypoint; use `SubMiner --sync-cli --help` for its sync-specific help. The `subminer sync` launcher command selects this entrypoint automatically and runs AppImages in Node-only mode, so remote sync does not require a graphical session.

 ### Sync window

-`subminer sync --ui` (or **Sync Stats & History** in the tray menu) opens a dedicated window for the same engine:
+`subminer sync --ui` opens a dedicated window for the same engine in a detached app process, returning the shell immediately. Closing that standalone-launched window exits its app instance. Opening **Sync Stats & History** from the tray keeps the resident app running when the window closes:

- **Devices** — saved hosts with a per-host direction (two-way / push / pull), an auto-sync toggle, last-sync status, and one-click **Sync now** / **Test** / **Remove**. Hosts synced from the command line appear here automatically.
- **Add a device** — test SSH + remote SubMiner availability before saving, with a setup checklist for first-time SSH configuration.
- **Activity** — live stage-by-stage progress, remote output, and a merge summary (sessions, words, kanji, rollups) when a run finishes. Runs can be cancelled, and guard failures offer a one-click `--force` retry.
- **Snapshots** — create manual database snapshots (stored in `/tmp/subminer-db-snapshots/` by default), merge a snapshot file into the local database, or reveal/delete existing snapshots.
+- **Devices:** saved hosts with a per-host direction (two-way / push / pull), an auto-sync toggle, last-sync status, and one-click **Sync now** / **Test** / **Remove**. Hosts synced from the command line appear here automatically.
+- **Add a device:** test SSH + remote SubMiner availability before saving, with a setup checklist for first-time SSH configuration.
+- **Activity:** live stage-by-stage progress, remote output, and separate merge summaries (sessions, words, kanji, rollups) for each machine updated by the run. Runs can be cancelled and can proceed while the app, stats server, or playback is active.
+- **Snapshots:** create manual database snapshots (stored in `/tmp/subminer-db-snapshots/` by default), merge a snapshot file into the local database, or reveal/delete existing snapshots.

-Hosts with **Auto-sync** enabled are synced in the background on a configurable interval (default every 60 minutes) whenever no mpv session or stats server is using the database; results surface as overlay notifications. Host bookkeeping lives in `<config dir>/sync-hosts.json`.
+Hosts with **Auto-sync** enabled are synced in the background on a configurable interval (default every 60 minutes), including during active playback; results surface as overlay notifications. The unfinished playback session is skipped until a later sync sees it finalized. Host bookkeeping lives in `<config dir>/sync-hosts.json`.

 ## Common Commands

@@ -172,7 +172,7 @@ SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355  # Pin corre
 SubMiner.AppImage --help                  # Show all options
 ```

-`--check` performs connection and version checks without changing data. `--json` emits the NDJSON event protocol used by the sync window. `--ui` opens that window. `--make-temp` and `--remove-temp` are internal remote-transfer helpers and should normally be left to SubMiner. The packaged app's `--sync-cli` flag selects its headless sync-compatible entrypoint; the `subminer sync` launcher command proxies to it automatically.
+`--check` performs connection and version checks without changing data. `--json` emits the NDJSON event protocol used by the sync window. `--ui` opens that window in a detached app process and returns the shell immediately; closing a standalone-launched Sync window exits that app instance. `--make-temp` and `--remove-temp` are internal remote-transfer helpers and should normally be left to SubMiner. The packaged app's `--sync-cli` flag selects its headless sync-compatible entrypoint; the `subminer sync` launcher command proxies to it automatically.

 The tray menu includes `Export Logs`, which creates the same sanitized local-date log ZIP as `subminer logs -e` and shows the archive path when complete. Export sanitization masks common PII and secrets, including home-directory usernames, IP addresses, emails, auth/cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL query strings. The exported copy is sanitized; source log files remain unredacted on disk.

@@ -1,14 +1,17 @@
 import {
+  launchAppCommandDetached,
  launchAppBackgroundDetached,
  launchTexthookerOnly,
-  runAppCommandInteractive,
  runAppCommandWithInherit,
 } from '../mpv.js';
 import type { LauncherCommandContext } from './context.js';

 type AppCommandDeps = {
  runAppCommandWithInherit: (appPath: string, appArgs: string[]) => void;
-  runAppCommandInteractive: (appPath: string, appArgs: string[]) => void;
+  launchSyncUiDetached: (
+    appPath: string,
+    logLevel: LauncherCommandContext['args']['logLevel'],
+  ) => void;
  launchAppBackgroundDetached: (
    appPath: string,
    logLevel: LauncherCommandContext['args']['logLevel'],
@@ -17,7 +20,8 @@ type AppCommandDeps = {

 const defaultAppCommandDeps: AppCommandDeps = {
  runAppCommandWithInherit,
-  runAppCommandInteractive,
+  launchSyncUiDetached: (appPath, logLevel) =>
+    launchAppCommandDetached(appPath, ['--sync-window'], logLevel, 'sync-ui'),
  launchAppBackgroundDetached,
 };

@@ -34,7 +38,7 @@ export function runAppPassthroughCommand(
    return true;
  }
  if (args.syncUi) {
-    deps.runAppCommandInteractive(appPath, ['--sync-window']);
+    deps.launchSyncUiDetached(appPath, args.logLevel);
    return true;
  }
  if (!args.appPassthrough) {
@@ -206,7 +206,7 @@ test('app command starts default macOS background app detached from launcher', (
    runAppCommandWithInherit: () => {
      calls.push('attached');
    },
-    runAppCommandInteractive: () => calls.push('interactive'),
+    launchSyncUiDetached: () => calls.push('sync-ui'),
    launchAppBackgroundDetached: (appPath, logLevel) => {
      calls.push(`detached:${appPath}:${logLevel}`);
    },
@@ -226,7 +226,7 @@ test('app command starts default Linux background app detached from launcher', (
    runAppCommandWithInherit: () => {
      calls.push('attached');
    },
-    runAppCommandInteractive: () => calls.push('interactive'),
+    launchSyncUiDetached: () => calls.push('sync-ui'),
    launchAppBackgroundDetached: (appPath, logLevel) => {
      calls.push(`detached:${appPath}:${logLevel}`);
    },
@@ -247,7 +247,7 @@ test('app command keeps explicit passthrough args attached', () => {
    runAppCommandWithInherit: (_appPath, appArgs) => {
      forwarded.push(appArgs);
    },
-    runAppCommandInteractive: () => detached.push('interactive'),
+    launchSyncUiDetached: () => detached.push('sync-ui'),
    launchAppBackgroundDetached: () => {
      detached.push('detached');
    },
@@ -258,19 +258,19 @@ test('app command keeps explicit passthrough args attached', () => {
  assert.deepEqual(detached, []);
 });

-test('sync UI command attaches the app directly to the terminal', () => {
+test('sync UI command launches the app detached from the terminal', () => {
  const context = createContext();
  context.args.syncUi = true;
  const calls: string[] = [];

  const handled = runAppPassthroughCommand(context, {
    runAppCommandWithInherit: () => calls.push('piped'),
-    runAppCommandInteractive: (_appPath, appArgs) => calls.push(`direct:${appArgs.join(' ')}`),
+    launchSyncUiDetached: (appPath, logLevel) => calls.push(`sync-ui:${appPath}:${logLevel}`),
    launchAppBackgroundDetached: () => calls.push('detached'),
  });

  assert.equal(handled, true);
-  assert.deepEqual(calls, ['direct:--sync-window']);
+  assert.deepEqual(calls, ['sync-ui:/tmp/subminer.app:warn']);
 });

 test('mpv pre-app command exits non-zero when socket is not ready', async () => {
@@ -37,17 +37,7 @@ function createContext(): LauncherCommandContext {
      useRofi: false,
      history: false,
      sync: false,
-      syncHost: '',
-      syncSnapshotPath: '',
-      syncMergePath: '',
-      syncDirection: 'both',
-      syncRemoteCmd: '',
-      syncDbPath: '',
-      syncForce: false,
-      syncJson: false,
-      syncCheck: false,
-      syncMakeTemp: false,
-      syncRemoveTempPath: '',
+      syncCliTokens: [],
      syncUi: false,
      logLevel: 'info',
      logRotation: 7,
@@ -2,7 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import type { Args } from '../types.js';
 import type { LauncherCommandContext } from './context.js';
-import { buildSyncCliArgv, runSyncCommand, type SyncCommandDeps } from './sync-command.js';
+import { runSyncCommand, type SyncCommandDeps } from './sync-command.js';

 function makeContext(
  overrides: Partial<Args>,
@@ -11,17 +11,7 @@ function makeContext(
  return {
    args: {
      sync: true,
-      syncHost: '',
-      syncSnapshotPath: '',
-      syncMergePath: '',
-      syncDirection: 'both',
-      syncRemoteCmd: '',
-      syncDbPath: '',
-      syncForce: false,
-      syncJson: false,
-      syncCheck: false,
-      syncMakeTemp: false,
-      syncRemoveTempPath: '',
+      syncCliTokens: [],
      logLevel: 'warn',
      ...overrides,
    } as Args,
@@ -35,24 +25,6 @@ function makeContext(
  } as unknown as LauncherCommandContext;
 }

-function makeArgs(overrides: Partial<Parameters<typeof buildSyncCliArgv>[0]>) {
-  return {
-    syncHost: '',
-    syncSnapshotPath: '',
-    syncMergePath: '',
-    syncDirection: 'both' as const,
-    syncRemoteCmd: '',
-    syncDbPath: '',
-    syncForce: false,
-    syncJson: false,
-    syncCheck: false,
-    syncMakeTemp: false,
-    syncRemoveTempPath: '',
-    logLevel: 'warn' as const,
-    ...overrides,
-  };
-}
-
 test('runSyncCommand proxies sync argv to the app in --sync-cli mode', async () => {
  const spawned: Array<{ appPath: string; appArgs: string[] }> = [];
  const deps: Partial<SyncCommandDeps> = {
@@ -62,7 +34,7 @@ test('runSyncCommand proxies sync argv to the app in --sync-cli mode', async ()
  };

  assert.equal(
-    await runSyncCommand(makeContext({ syncHost: 'media-box', syncJson: true }), deps),
+    await runSyncCommand(makeContext({ syncCliTokens: ['media-box', '--json'] }), deps),
    true,
  );
  assert.deepEqual(spawned, [
@@ -76,19 +48,32 @@ test('runSyncCommand proxies sync argv to the app in --sync-cli mode', async ()
  assert.equal(spawned.length, 1);
 });

-test('buildSyncCliArgv forwards every sync option', () => {
-  assert.deepEqual(
-    buildSyncCliArgv(
-      makeArgs({
-        syncHost: 'media-box',
-        syncDirection: 'pull',
-        syncRemoteCmd: '/opt/SubMiner.AppImage',
-        syncDbPath: '/tmp/db.sqlite',
-        syncForce: true,
-        syncJson: true,
-        logLevel: 'debug',
-      }),
-    ),
+test('runSyncCommand forwards tokens verbatim and appends the effective log level', async () => {
+  const spawned: string[][] = [];
+  const deps: Partial<SyncCommandDeps> = {
+    runAppCommand: (_appPath, appArgs) => {
+      spawned.push(appArgs);
+    },
+  };
+
+  await runSyncCommand(
+    makeContext({
+      syncCliTokens: [
+        'media-box',
+        '--pull',
+        '--remote-cmd',
+        '/opt/SubMiner.AppImage',
+        '--db',
+        '/tmp/db.sqlite',
+        '--force',
+        '--json',
+      ],
+      logLevel: 'debug',
+    }),
+    deps,
+  );
+
+  assert.deepEqual(spawned, [
    [
      '--sync-cli',
      'sync',
@@ -103,32 +88,7 @@ test('buildSyncCliArgv forwards every sync option', () => {
      '--log-level',
      'debug',
    ],
-  );
-
-  assert.deepEqual(
-    buildSyncCliArgv(makeArgs({ syncSnapshotPath: '/tmp/out.sqlite' })),
-    ['--sync-cli', 'sync', '--snapshot', '/tmp/out.sqlite', '--log-level', 'warn'],
-  );
-
-  assert.deepEqual(
-    buildSyncCliArgv(makeArgs({ syncHost: 'media-box', syncCheck: true })),
-    ['--sync-cli', 'sync', 'media-box', '--check', '--log-level', 'warn'],
-  );
-
-  assert.deepEqual(
-    buildSyncCliArgv(makeArgs({ syncMakeTemp: true })),
-    ['--sync-cli', 'sync', '--make-temp', '--log-level', 'warn'],
-  );
-
-  assert.deepEqual(
-    buildSyncCliArgv(makeArgs({ syncRemoveTempPath: '/tmp/subminer-sync-x' })),
-    ['--sync-cli', 'sync', '--remove-temp', '/tmp/subminer-sync-x', '--log-level', 'warn'],
-  );
-
-  assert.deepEqual(
-    buildSyncCliArgv(makeArgs({ syncMergePath: '/tmp/in.sqlite', syncForce: true })),
-    ['--sync-cli', 'sync', '--merge', '/tmp/in.sqlite', '--force', '--log-level', 'warn'],
-  );
+  ]);
 });

 test('runSyncCommand fails with a clear message when the app binary is missing', async () => {
@@ -142,7 +102,7 @@ test('runSyncCommand fails with a clear message when the app binary is missing',
  };

  await assert.rejects(
-    () => runSyncCommand(makeContext({ syncHost: 'media-box' }, null), deps),
+    () => runSyncCommand(makeContext({ syncCliTokens: ['media-box'] }, null), deps),
    /SubMiner app binary not found \(sync runs inside the app\)/,
  );
 });
@@ -1,6 +1,6 @@
+import { SYNC_CLI_FLAG } from '../../src/core/services/stats-sync/cli-args.js';
 import { fail } from '../log.js';
 import { runAppCommandInteractive } from '../mpv.js';
-import type { Args } from '../types.js';
 import type { LauncherCommandContext } from './context.js';

 export interface SyncCommandDeps {
@@ -13,46 +13,12 @@ const defaultSyncCommandDeps: SyncCommandDeps = {
  fail,
 };

-type SyncArgs = Pick<
-  Args,
-  | 'syncHost'
-  | 'syncSnapshotPath'
-  | 'syncMergePath'
-  | 'syncDirection'
-  | 'syncRemoteCmd'
-  | 'syncDbPath'
-  | 'syncForce'
-  | 'syncJson'
-  | 'syncCheck'
-  | 'syncMakeTemp'
-  | 'syncRemoveTempPath'
-  | 'logLevel'
->;
-
-/** Rebuild the app's --sync-cli argv from the launcher's parsed sync args. */
-export function buildSyncCliArgv(args: SyncArgs): string[] {
-  const argv = ['--sync-cli', 'sync'];
-  if (args.syncHost) argv.push(args.syncHost);
-  if (args.syncSnapshotPath) argv.push('--snapshot', args.syncSnapshotPath);
-  if (args.syncMergePath) argv.push('--merge', args.syncMergePath);
-  if (args.syncMakeTemp) argv.push('--make-temp');
-  if (args.syncRemoveTempPath) argv.push('--remove-temp', args.syncRemoveTempPath);
-  if (args.syncDirection === 'push') argv.push('--push');
-  if (args.syncDirection === 'pull') argv.push('--pull');
-  if (args.syncCheck) argv.push('--check');
-  if (args.syncRemoteCmd) argv.push('--remote-cmd', args.syncRemoteCmd);
-  if (args.syncDbPath) argv.push('--db', args.syncDbPath);
-  if (args.syncForce) argv.push('--force');
-  if (args.syncJson) argv.push('--json');
-  argv.push('--log-level', args.logLevel);
-  return argv;
-}
-
 /**
 * `subminer sync` is a thin proxy: the sync engine only executes inside the
- * SubMiner app (--sync-cli mode, libsql), so the launcher and the app cannot
- * drift apart. The launcher contributes its parser/help and app discovery;
- * the child owns the terminal and its exit code becomes the launcher's.
+ * SubMiner app (--sync-cli mode, libsql). The launcher contributes its
+ * parser/help and app discovery; the app's parseSyncCliTokens owns validation,
+ * so its errors reach the terminal through the child's inherited stdio. The
+ * child owns the terminal and its exit code becomes the launcher's.
 */
 export async function runSyncCommand(
  context: LauncherCommandContext,
@@ -68,6 +34,12 @@ export async function runSyncCommand(
    );
    return true; // fail() never returns; this only satisfies control-flow analysis
  }
-  deps.runAppCommand(context.appPath, buildSyncCliArgv(context.args));
+  deps.runAppCommand(context.appPath, [
+    SYNC_CLI_FLAG,
+    'sync',
+    ...context.args.syncCliTokens,
+    '--log-level',
+    context.args.logLevel,
+  ]);
  return true;
 }
@@ -136,17 +136,7 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
    statsCleanupLifetime: false,
    statsLogLevel: null,
    syncTriggered: false,
-    syncHost: null,
-    syncSnapshotPath: null,
-    syncMergePath: null,
-    syncDirection: 'both',
-    syncRemoteCmd: null,
-    syncDbPath: null,
-    syncForce: false,
-    syncJson: false,
-    syncCheck: false,
-    syncMakeTemp: false,
-    syncRemoveTempPath: '',
+    syncCliTokens: [],
    syncLogLevel: null,
    syncUiTriggered: false,
    syncUiLogLevel: null,
@@ -197,17 +187,7 @@ test('applyInvocationsToArgs maps settings invocation to settings window', () =>
    statsCleanupLifetime: false,
    statsLogLevel: null,
    syncTriggered: false,
-    syncHost: null,
-    syncSnapshotPath: null,
-    syncMergePath: null,
-    syncDirection: 'both',
-    syncRemoteCmd: null,
-    syncDbPath: null,
-    syncForce: false,
-    syncJson: false,
-    syncCheck: false,
-    syncMakeTemp: false,
-    syncRemoveTempPath: '',
+    syncCliTokens: [],
    syncLogLevel: null,
    syncUiTriggered: false,
    syncUiLogLevel: null,
@@ -251,17 +231,7 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
      statsCleanupLifetime: false,
      statsLogLevel: null,
      syncTriggered: false,
-      syncHost: null,
-      syncSnapshotPath: null,
-      syncMergePath: null,
-      syncDirection: 'both',
-      syncRemoteCmd: null,
-      syncDbPath: null,
-      syncForce: false,
-      syncJson: false,
-      syncCheck: false,
-      syncMakeTemp: false,
-      syncRemoveTempPath: '',
+      syncCliTokens: [],
      syncLogLevel: null,
      syncUiTriggered: false,
      syncUiLogLevel: null,
@@ -303,17 +273,7 @@ test('applyInvocationsToArgs maps texthooker browser-open request', () => {
    statsCleanupLifetime: false,
    statsLogLevel: null,
    syncTriggered: false,
-    syncHost: null,
-    syncSnapshotPath: null,
-    syncMergePath: null,
-    syncDirection: 'both',
-    syncRemoteCmd: null,
-    syncDbPath: null,
-    syncForce: false,
-    syncJson: false,
-    syncCheck: false,
-    syncMakeTemp: false,
-    syncRemoveTempPath: '',
+    syncCliTokens: [],
    syncLogLevel: null,
    syncUiTriggered: false,
    syncUiLogLevel: null,
@@ -200,17 +200,7 @@ export function createDefaultArgs(
    useRofi: false,
    history: false,
    sync: false,
-    syncHost: '',
-    syncSnapshotPath: '',
-    syncMergePath: '',
-    syncDirection: 'both',
-    syncRemoteCmd: '',
-    syncDbPath: '',
-    syncForce: false,
-    syncJson: false,
-    syncCheck: false,
-    syncMakeTemp: false,
-    syncRemoveTempPath: '',
+    syncCliTokens: [],
    syncUi: false,
    logLevel: loggingConfig.level ?? 'warn',
    logRotation: loggingConfig.rotation ?? 7,
@@ -279,17 +269,7 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
  }
  if (invocations.syncTriggered) {
    parsed.sync = true;
-    parsed.syncHost = invocations.syncHost ?? '';
-    parsed.syncSnapshotPath = invocations.syncSnapshotPath ?? '';
-    parsed.syncMergePath = invocations.syncMergePath ?? '';
-    parsed.syncDirection = invocations.syncDirection;
-    parsed.syncRemoteCmd = invocations.syncRemoteCmd ?? '';
-    parsed.syncDbPath = invocations.syncDbPath ?? '';
-    parsed.syncForce = invocations.syncForce;
-    parsed.syncJson = invocations.syncJson;
-    parsed.syncCheck = invocations.syncCheck;
-    parsed.syncMakeTemp = invocations.syncMakeTemp;
-    parsed.syncRemoveTempPath = invocations.syncRemoveTempPath ?? '';
+    parsed.syncCliTokens = invocations.syncCliTokens;
    if (invocations.syncLogLevel) parsed.logLevel = parseLogLevel(invocations.syncLogLevel);
  }
  if (invocations.syncUiTriggered) {
@@ -43,42 +43,66 @@ test('parseCliPrograms captures texthooker browser-open flag', () => {
  assert.equal(result.invocations.texthookerOpenBrowser, true);
 });

-test('parseCliPrograms captures one-way sync directions', () => {
+test('parseCliPrograms lowers sync options into app-owned CLI tokens', () => {
  const push = parseCliPrograms(['sync', 'media-box', '--push'], 'subminer');
+  assert.equal(push.invocations.syncTriggered, true);
+  assert.deepEqual(push.invocations.syncCliTokens, ['media-box', '--push']);
+
  const pull = parseCliPrograms(['sync', 'media-box', '--pull'], 'subminer');
-
-  assert.equal(push.invocations.syncDirection, 'push');
-  assert.equal(pull.invocations.syncDirection, 'pull');
-});
-
-test('parseCliPrograms rejects conflicting or hostless one-way sync directions', () => {
-  assert.throws(
-    () => parseCliPrograms(['sync', 'media-box', '--push', '--pull'], 'subminer'),
-    /--push and --pull cannot be combined/,
-  );
-  assert.throws(
-    () => parseCliPrograms(['sync', '--snapshot', '/tmp/stats.sqlite', '--push'], 'subminer'),
-    /--push and --pull require a host/,
-  );
-});
-
-test('parseCliPrograms captures sync --json and --check flags', () => {
-  const json = parseCliPrograms(['sync', 'media-box', '--json'], 'subminer');
-  assert.equal(json.invocations.syncJson, true);
-  assert.equal(json.invocations.syncCheck, false);
+  assert.deepEqual(pull.invocations.syncCliTokens, ['media-box', '--pull']);

  const check = parseCliPrograms(['sync', 'media-box', '--check', '--json'], 'subminer');
-  assert.equal(check.invocations.syncCheck, true);
-  assert.equal(check.invocations.syncJson, true);
-  assert.equal(check.invocations.syncHost, 'media-box');
+  assert.deepEqual(check.invocations.syncCliTokens, ['media-box', '--check', '--json']);
+
+  const full = parseCliPrograms(
+    [
+      'sync',
+      'media-box',
+      '--remote-cmd',
+      '/opt/SubMiner.AppImage',
+      '--db',
+      '/tmp/db.sqlite',
+      '--force',
+      '--log-level',
+      'debug',
+    ],
+    'subminer',
+  );
+  assert.deepEqual(full.invocations.syncCliTokens, [
+    'media-box',
+    '--remote-cmd',
+    '/opt/SubMiner.AppImage',
+    '--db',
+    '/tmp/db.sqlite',
+    '--force',
+  ]);
+  assert.equal(full.invocations.syncLogLevel, 'debug');
+
+  const snapshot = parseCliPrograms(['sync', '--snapshot', '/tmp/out.sqlite'], 'subminer');
+  assert.deepEqual(snapshot.invocations.syncCliTokens, ['--snapshot', '/tmp/out.sqlite']);
+
+  const merge = parseCliPrograms(['sync', '--merge', '/tmp/in.sqlite'], 'subminer');
+  assert.deepEqual(merge.invocations.syncCliTokens, ['--merge', '/tmp/in.sqlite']);
+
+  const makeTemp = parseCliPrograms(['sync', '--make-temp'], 'subminer');
+  assert.deepEqual(makeTemp.invocations.syncCliTokens, ['--make-temp']);
+
+  const removeTemp = parseCliPrograms(
+    ['sync', '--remove-temp', '/tmp/subminer-sync-x'],
+    'subminer',
+  );
+  assert.deepEqual(removeTemp.invocations.syncCliTokens, ['--remove-temp', '/tmp/subminer-sync-x']);
 });

-test('parseCliPrograms rejects invalid sync --check combinations', () => {
-  assert.throws(() => parseCliPrograms(['sync', '--check'], 'subminer'), /--check requires a host/);
-  assert.throws(
-    () => parseCliPrograms(['sync', 'media-box', '--check', '--push'], 'subminer'),
-    /--check cannot be combined/,
-  );
+test('parseCliPrograms leaves sync validation to the app parser', () => {
+  // Invalid combinations are forwarded; the app's parseSyncCliTokens rejects them.
+  const invalid = parseCliPrograms(['sync', 'media-box', '--push', '--pull'], 'subminer');
+  assert.equal(invalid.invocations.syncTriggered, true);
+  assert.deepEqual(invalid.invocations.syncCliTokens, ['media-box', '--push', '--pull']);
+
+  const empty = parseCliPrograms(['sync'], 'subminer');
+  assert.equal(empty.invocations.syncTriggered, true);
+  assert.deepEqual(empty.invocations.syncCliTokens, []);
 });

 test('parseCliPrograms captures sync --ui', () => {
@@ -91,3 +115,16 @@ test('parseCliPrograms captures sync --ui', () => {
    /--ui cannot be combined/,
  );
 });
+
+test('parseCliPrograms rejects sync --ui with --remote-cmd', () => {
+  assert.throws(
+    () => parseCliPrograms(['sync', '--ui', '--remote-cmd', '/opt/SubMiner.AppImage'], 'subminer'),
+    { message: 'Sync --ui cannot be combined with other sync options.' },
+  );
+});
+
+test('parseCliPrograms rejects sync --ui with --db', () => {
+  assert.throws(() => parseCliPrograms(['sync', '--ui', '--db', '/tmp/db.sqlite'], 'subminer'), {
+    message: 'Sync --ui cannot be combined with other sync options.',
+  });
+});
@@ -39,17 +39,7 @@ export interface CliInvocations {
  statsCleanupLifetime: boolean;
  statsLogLevel: string | null;
  syncTriggered: boolean;
-  syncHost: string | null;
-  syncSnapshotPath: string | null;
-  syncMergePath: string | null;
-  syncDirection: 'both' | 'push' | 'pull';
-  syncRemoteCmd: string | null;
-  syncDbPath: string | null;
-  syncForce: boolean;
-  syncJson: boolean;
-  syncCheck: boolean;
-  syncMakeTemp: boolean;
-  syncRemoveTempPath: string | null;
+  syncCliTokens: string[];
  syncLogLevel: string | null;
  syncUiTriggered: boolean;
  syncUiLogLevel: string | null;
@@ -181,17 +171,7 @@ export function parseCliPrograms(
  let statsCleanupLifetime = false;
  let statsLogLevel: string | null = null;
  let syncTriggered = false;
-  let syncHost: string | null = null;
-  let syncSnapshotPath: string | null = null;
-  let syncMergePath: string | null = null;
-  let syncDirection: 'both' | 'push' | 'pull' = 'both';
-  let syncRemoteCmd: string | null = null;
-  let syncDbPath: string | null = null;
-  let syncForce = false;
-  let syncJson = false;
-  let syncCheck = false;
-  let syncMakeTemp = false;
-  let syncRemoveTempPath: string | null = null;
+  let syncCliTokens: string[] = [];
  let syncLogLevel: string | null = null;
  let syncUiTriggered = false;
  let syncUiLogLevel: string | null = null;
@@ -360,6 +340,8 @@ export function parseCliPrograms(
          check ||
          makeTemp ||
          removeTemp ||
+          options.remoteCmd !== undefined ||
+          options.db !== undefined ||
          options.json === true ||
          options.force === true
        ) {
@@ -369,49 +351,25 @@ export function parseCliPrograms(
        syncUiLogLevel = typeof options.logLevel === 'string' ? options.logLevel : null;
        return;
      }
-      if (push && pull) {
-        throw new Error('Sync --push and --pull cannot be combined.');
-      }
-      if ((push || pull) && !host) {
-        throw new Error('Sync --push and --pull require a host.');
-      }
-      if (check && !host) {
-        throw new Error('Sync --check requires a host.');
-      }
-      if (check && (push || pull || snapshot || merge)) {
-        throw new Error(
-          'Sync --check cannot be combined with --push, --pull, --snapshot, or --merge.',
-        );
-      }
-      if ((makeTemp || removeTemp) && (push || pull || check)) {
-        throw new Error('Sync --make-temp/--remove-temp cannot be combined with other sync options.');
-      }
-      const modes = [
-        Boolean(host),
-        Boolean(snapshot),
-        Boolean(merge),
-        makeTemp,
-        Boolean(removeTemp),
-      ].filter(Boolean).length;
-      if (modes === 0) {
-        throw new Error('Sync requires a host, --snapshot <file>, or --merge <file>.');
-      }
-      if (modes > 1) {
-        throw new Error('Sync host, --snapshot, --merge, --make-temp, and --remove-temp cannot be combined.');
-      }
+      // No validation here: the app's parseSyncCliTokens owns the sync rules
+      // and its error text reaches the terminal through the child's stdio.
+      const remoteCmd = typeof options.remoteCmd === 'string' ? options.remoteCmd.trim() : '';
+      const dbPath = typeof options.db === 'string' ? options.db.trim() : '';
+      const tokens: string[] = [];
+      if (host) tokens.push(host);
+      if (snapshot) tokens.push('--snapshot', snapshot);
+      if (merge) tokens.push('--merge', merge);
+      if (makeTemp) tokens.push('--make-temp');
+      if (removeTemp) tokens.push('--remove-temp', removeTemp);
+      if (push) tokens.push('--push');
+      if (pull) tokens.push('--pull');
+      if (check) tokens.push('--check');
+      if (remoteCmd) tokens.push('--remote-cmd', remoteCmd);
+      if (dbPath) tokens.push('--db', dbPath);
+      if (options.force === true) tokens.push('--force');
+      if (options.json === true) tokens.push('--json');
      syncTriggered = true;
-      syncHost = host || null;
-      syncSnapshotPath = snapshot || null;
-      syncMergePath = merge || null;
-      syncDirection = push ? 'push' : pull ? 'pull' : 'both';
-      syncRemoteCmd =
-        typeof options.remoteCmd === 'string' ? options.remoteCmd.trim() || null : null;
-      syncDbPath = typeof options.db === 'string' ? options.db.trim() || null : null;
-      syncForce = options.force === true;
-      syncJson = options.json === true;
-      syncCheck = check;
-      syncMakeTemp = makeTemp;
-      syncRemoveTempPath = removeTemp || null;
+      syncCliTokens = tokens;
      syncLogLevel = typeof options.logLevel === 'string' ? options.logLevel : null;
    });

@@ -527,17 +485,7 @@ export function parseCliPrograms(
      statsCleanupLifetime,
      statsLogLevel,
      syncTriggered,
-      syncHost,
-      syncSnapshotPath,
-      syncMergePath,
-      syncDirection,
-      syncRemoteCmd,
-      syncDbPath,
-      syncForce,
-      syncJson,
-      syncCheck,
-      syncMakeTemp,
-      syncRemoveTempPath,
+      syncCliTokens,
      syncLogLevel,
      syncUiTriggered,
      syncUiLogLevel,
@@ -1,38 +1,12 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import { Database } from 'bun:sqlite';
-import { resolveConfigDir } from '../src/config/path-resolution.js';
-import { readLauncherMainConfigObject } from './config/shared-config-reader.js';
 import type { HistoryVideoRow } from './history-types.js';
-import { resolvePathMaybe } from './util.js';
+import { resolveImmersionDbPath } from '../src/core/services/stats-sync/db-path.js';
 import {
  isReadonlyWalRetryError,
  withReadonlyWalRetry,
 } from '../src/core/services/stats-sync/wal-retry.js';

-export { isReadonlyWalRetryError, withReadonlyWalRetry };
-
-export function resolveImmersionDbPath(): string {
-  const root = readLauncherMainConfigObject();
-  const tracking =
-    root?.immersionTracking &&
-    typeof root.immersionTracking === 'object' &&
-    !Array.isArray(root.immersionTracking)
-      ? (root.immersionTracking as Record<string, unknown>)
-      : null;
-  const configured = typeof tracking?.dbPath === 'string' ? tracking.dbPath.trim() : '';
-  if (configured) return resolvePathMaybe(configured);
-
-  const configDir = resolveConfigDir({
-    platform: process.platform,
-    appDataDir: process.env.APPDATA,
-    xdgConfigHome: process.env.XDG_CONFIG_HOME,
-    homeDir: os.homedir(),
-    existsSync: fs.existsSync,
-  });
-  return path.join(configDir, 'immersion.sqlite');
-}
+export { isReadonlyWalRetryError, resolveImmersionDbPath, withReadonlyWalRetry };

 interface RawHistoryRow {
  video_id: number;
@@ -31,17 +31,7 @@ function createArgs(): Args {
    useRofi: false,
    history: false,
    sync: false,
-    syncHost: '',
-    syncSnapshotPath: '',
-    syncMergePath: '',
-    syncDirection: 'both',
-    syncRemoteCmd: '',
-    syncDbPath: '',
-    syncForce: false,
-    syncJson: false,
-    syncCheck: false,
-    syncMakeTemp: false,
-    syncRemoveTempPath: '',
+    syncCliTokens: [],
    syncUi: false,
    logLevel: 'info',
    logRotation: 7,
@@ -119,6 +119,37 @@ test('runAppCommandCaptureOutput transports Linux AppImage args through environm
  }
 });

+test('runAppCommandCaptureOutput runs Linux AppImage sync in Node-only mode', () => {
+  const { dir } = createTempSocketPath();
+  const appPath = path.join(dir, 'SubMiner.AppImage');
+  fs.writeFileSync(
+    appPath,
+    [
+      '#!/bin/sh',
+      'printf "args:%s\\n" "$*"',
+      'printf "electron-node:%s\\n" "$ELECTRON_RUN_AS_NODE"',
+      'printf "argc:%s\\n" "$SUBMINER_APP_ARGC"',
+      'printf "arg0:%s\\n" "$SUBMINER_APP_ARG_0"',
+      '',
+    ].join('\n'),
+  );
+  fs.chmodSync(appPath, 0o755);
+
+  try {
+    const result = withPlatform('linux', () =>
+      runAppCommandCaptureOutput(appPath, ['--sync-cli', 'sync', '--snapshot', '/tmp/out']),
+    );
+
+    assert.equal(result.status, 0);
+    assert.match(result.stdout, /^args:-e /m);
+    assert.match(result.stdout, /^electron-node:1$/m);
+    assert.match(result.stdout, /^argc:4$/m);
+    assert.match(result.stdout, /^arg0:--sync-cli$/m);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('parseMpvArgString preserves empty quoted tokens', () => {
  assert.deepEqual(parseMpvArgString('--title "" --force-media-title \'\' --pause'), [
    '--title',
@@ -572,17 +603,7 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
    useRofi: false,
    history: false,
    sync: false,
-    syncHost: '',
-    syncSnapshotPath: '',
-    syncMergePath: '',
-    syncDirection: 'both',
-    syncRemoteCmd: '',
-    syncDbPath: '',
-    syncForce: false,
-    syncJson: false,
-    syncCheck: false,
-    syncMakeTemp: false,
-    syncRemoveTempPath: '',
+    syncCliTokens: [],
    syncUi: false,
    logLevel: 'error',
    logRotation: 7,
@@ -1277,6 +1277,15 @@ function shouldTransportAppArgsForAppImage(appPath: string): boolean {
  return process.platform === 'linux' && /\.AppImage$/i.test(appPath);
 }

+const APPIMAGE_SYNC_NODE_RUNNER = [
+  'const root=process.env.APPDIR+"/resources/app.asar";',
+  'const {runSyncCliFromProcess}=require(root+"/dist/main/sync-cli.js");',
+  'const count=Number(process.env.SUBMINER_APP_ARGC);',
+  'const argv=[process.execPath,...Array.from({length:count},(_,i)=>process.env["SUBMINER_APP_ARG_"+i]??"")];',
+  'runSyncCliFromProcess(argv,require(root+"/package.json").version)',
+  '.then(code=>process.exit(code),error=>{console.error(error);process.exit(1)});',
+].join('');
+
 function buildAppEnv(
  baseEnv: NodeJS.ProcessEnv = process.env,
  extraEnv: NodeJS.ProcessEnv = {},
@@ -1432,6 +1441,16 @@ function maybeCaptureAppArgs(appArgs: string[]): boolean {

 function resolveAppSpawnTarget(appPath: string, appArgs: string[]): SpawnTarget {
  if (shouldTransportAppArgsForAppImage(appPath)) {
+    if (appArgs[0] === '--sync-cli') {
+      return {
+        command: appPath,
+        args: ['-e', APPIMAGE_SYNC_NODE_RUNNER],
+        env: {
+          ...buildTransportedAppArgsEnv(appArgs),
+          ELECTRON_RUN_AS_NODE: '1',
+        },
+      };
+    }
    return {
      command: appPath,
      args: [],
@@ -4,17 +4,11 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { Database } from 'bun:sqlite';
-import { openLibsqlSyncDb } from '../../src/core/services/stats-sync/libsql-driver.js';
-import { createDbSnapshot as createDbSnapshotWith } from '../../src/core/services/stats-sync/shared.js';
-import { mergeSnapshotIntoDb as mergeSnapshotIntoDbWith } from '../../src/core/services/stats-sync/merge.js';
-
-// The engine only executes inside the app (libsql driver) in production, so
-// these merge tests run through that same binding; bun:sqlite is used only to
-// build fixtures and inspect results.
-const createDbSnapshot = (dbPath: string, outPath: string) =>
-  createDbSnapshotWith(openLibsqlSyncDb, dbPath, outPath);
-const mergeSnapshotIntoDb = (localDbPath: string, snapshotPath: string) =>
-  mergeSnapshotIntoDbWith(openLibsqlSyncDb, localDbPath, snapshotPath);
+// The engine executes on libsql in production; these merge tests run through
+// that same driver. bun:sqlite is used only to build fixtures and inspect
+// results.
+import { createDbSnapshot } from '../../src/core/services/stats-sync/shared.js';
+import { mergeSnapshotIntoDb } from '../../src/core/services/stats-sync/merge.js';
 import {
  createImmersionDbFixture,
  insertFixtureSession,
@@ -114,17 +114,8 @@ export interface Args {
  useRofi: boolean;
  history: boolean;
  sync: boolean;
-  syncHost: string;
-  syncSnapshotPath: string;
-  syncMergePath: string;
-  syncDirection: 'both' | 'push' | 'pull';
-  syncRemoteCmd: string;
-  syncDbPath: string;
-  syncForce: boolean;
-  syncJson: boolean;
-  syncCheck: boolean;
-  syncMakeTemp: boolean;
-  syncRemoveTempPath: string;
+  /** App-owned sync argv tokens forwarded verbatim to `--sync-cli sync`. */
+  syncCliTokens: string[];
  syncUi: boolean;
  logLevel: LogLevel;
  logRotation: LogRotation;
@@ -23,7 +23,7 @@
    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:settings && bun run build:syncui && bun run build:launcher && bun run build:assets",
    "build:renderer": "esbuild src/renderer/renderer.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/renderer/renderer.js --sourcemap",
    "build:settings": "esbuild src/settings/settings.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/settings/settings.js --sourcemap",
-    "build:syncui": "esbuild src/syncui/syncui.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/syncui/syncui.js --sourcemap",
+    "build:syncui": "esbuild src/syncui/syncui.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/syncui/syncui.js --sourcemap && esbuild src/preload-syncui.ts --bundle --platform=node --format=cjs --target=node20 --external:electron --outfile=dist/preload-syncui.js --sourcemap",
    "changelog:build": "bun run scripts/build-changelog.ts build-release",
    "changelog:check": "bun run scripts/build-changelog.ts check",
    "changelog:docs": "bun run scripts/build-changelog.ts docs",
@@ -0,0 +1,16 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+test('build:syncui bundles the sandboxed preload and keeps Electron external', () => {
+  const packageJson = JSON.parse(
+    fs.readFileSync(path.join(import.meta.dir, '..', 'package.json'), 'utf8'),
+  ) as { scripts: Record<string, string> };
+  const command = packageJson.scripts['build:syncui'] ?? '';
+
+  assert.match(command, /src\/preload-syncui\.ts/);
+  assert.match(command, /--bundle/);
+  assert.match(command, /--external:electron/);
+  assert.match(command, /--outfile=dist\/preload-syncui\.js/);
+});
@@ -168,7 +168,14 @@ test('startAppLifecycle defers quit until async cleanup settles', async () => {
  assert.ok(releaseCleanup);
  (releaseCleanup as () => void)();
  await cleanupDone;
+  // The re-quit must not fire in the microtask turn of the will-quit
+  // dispatch: Electron drops a quit issued while the prevented quit is
+  // still unwinding, leaving a windowless process alive.
  await Promise.resolve();
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.deepEqual(calls, []);
+  await new Promise((resolve) => setImmediate(resolve));
  assert.deepEqual(calls, ['quitApp']);
 });

@@ -219,7 +219,11 @@ export function startAppLifecycle(initialArgs: CliArgs, deps: AppLifecycleServic
      .finally(() => {
        quitCleanupPending = false;
        quitCleanupComplete = true;
-        deps.quitApp();
+        // A cleanup promise that settles in a microtask would re-quit while
+        // Electron is still unwinding the prevented quit, and that quit call
+        // is silently dropped, leaving a windowless process alive. Re-issue
+        // the quit from a fresh macrotask instead.
+        setImmediate(() => deps.quitApp());
      });
  });

@@ -51,10 +51,11 @@ test('parseSyncCliTokens handles the temp-dir protocol modes', () => {
  assert.equal(parseSyncCliTokens(['sync', '--make-temp', '--remove-temp', '/tmp/x']).kind, 'error');
 });

-test('parseSyncCliTokens mirrors launcher sync validation', () => {
+test('parseSyncCliTokens owns the sync CLI validation rules', () => {
  assert.equal(parseSyncCliTokens([]).kind, 'error');
  assert.equal(parseSyncCliTokens(['sync']).kind, 'error');
  assert.equal(parseSyncCliTokens(['sync', 'h', '--push', '--pull']).kind, 'error');
+  assert.equal(parseSyncCliTokens(['sync', '--snapshot', '/tmp/x', '--push']).kind, 'error');
  assert.equal(parseSyncCliTokens(['sync', '--check']).kind, 'error');
  assert.equal(parseSyncCliTokens(['sync', '--check', '--snapshot', '/tmp/x', 'h']).kind, 'error');
  assert.equal(parseSyncCliTokens(['sync', 'h', '--snapshot', '/tmp/x']).kind, 'error');
@@ -16,8 +16,9 @@ export function extractSyncCliTokens(argv: readonly string[]): string[] | null {

 /**
 * Parse launcher-style sync argv (`sync [host] [--snapshot f] ...`) for the
- * app's --sync-cli mode. Mirrors the launcher's `subminer sync` validation so
- * both entry points accept the same command lines and fail the same way.
+ * app's --sync-cli mode. This is the single owner of sync CLI validation:
+ * the launcher forwards `subminer sync` tokens verbatim, so both entry
+ * points accept the same command lines and fail the same way.
 */
 export function parseSyncCliTokens(tokens: readonly string[]): ParsedSyncCli {
  if (tokens.includes('--help') || tokens.includes('-h')) return { kind: 'help' };
@@ -120,7 +121,6 @@ export function parseSyncCliTokens(tokens: readonly string[]): ParsedSyncCli {
  return {
    kind: 'run',
    args: {
-      sync: true,
      syncHost: host,
      syncSnapshotPath: snapshot,
      syncMergePath: merge,
@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveConfigFilePath } from '../../../config/path-resolution';
+import { parseConfigContent } from '../../../config/parse';
+import { getDefaultConfigDir } from '../../../shared/setup-state';
+
+/**
+ * Default immersion stats database location, shared by the launcher's history
+ * command and the app's --sync-cli mode: honor a configured
+ * immersionTracking.dbPath (raw main-config read, tolerant of comments), else
+ * <configDir>/immersion.sqlite. Electron- and libsql-free on purpose so the
+ * bun launcher can import it.
+ */
+export function resolveImmersionDbPath(): string {
+  const configPath = resolveConfigFilePath({
+    appDataDir: process.env.APPDATA,
+    xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    homeDir: os.homedir(),
+    existsSync: fs.existsSync,
+  });
+  let configured = '';
+  try {
+    const parsed = parseConfigContent(configPath, fs.readFileSync(configPath, 'utf8'));
+    const tracking =
+      parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>).immersionTracking
+        : null;
+    if (tracking && typeof tracking === 'object' && !Array.isArray(tracking)) {
+      const dbPath = (tracking as Record<string, unknown>).dbPath;
+      if (typeof dbPath === 'string') configured = dbPath.trim();
+    }
+  } catch {
+    // no config or unreadable config → default location
+  }
+  if (configured) {
+    return configured.startsWith('~')
+      ? path.join(os.homedir(), configured.slice(1))
+      : configured;
+  }
+  return path.join(getDefaultConfigDir(), 'immersion.sqlite');
+}
@@ -1,42 +0,0 @@
-// Minimal SQLite driver surface the stats-sync engine runs against. The
-// launcher binds it to bun:sqlite; the Electron app binds it to libsql. Both
-// implementations must cache prepared statements per SQL string in query():
-// the merge runs one insert per copied row, so re-preparing would dominate
-// merge time.
-
-export interface SyncDbRunResult {
-  changes: number;
-  lastInsertRowid: number | bigint;
-}
-
-export interface SyncDbStatement {
-  run(...params: unknown[]): SyncDbRunResult;
-  get(...params: unknown[]): unknown;
-  all(...params: unknown[]): unknown[];
-}
-
-export interface SyncDbOpenOptions {
-  readonly?: boolean;
-  readwrite?: boolean;
-  create?: boolean;
-}
-
-export interface SyncDb {
-  /** Prepare (or reuse a cached prepared statement for) the given SQL. */
-  query(sql: string): SyncDbStatement;
-  /** Execute SQL that returns no rows (pragmas, transaction control). */
-  exec(sql: string): void;
-  close(): void;
-}
-
-export type OpenSyncDb = (dbPath: string, options: SyncDbOpenOptions) => SyncDb;
-
-export type SqlRow = Record<string, unknown>;
-
-export function selectAll(db: SyncDb, sql: string, params: unknown[] = []): SqlRow[] {
-  return db.query(sql).all(...params) as SqlRow[];
-}
-
-export function selectOne(db: SyncDb, sql: string, params: unknown[] = []): SqlRow | undefined {
-  return (db.query(sql).get(...params) ?? undefined) as SqlRow | undefined;
-}
@@ -1,25 +1,48 @@
 import { Database } from '../immersion-tracker/sqlite';
-import type { OpenSyncDb, SyncDb, SyncDbRunResult, SyncDbStatement } from './driver';
+import type { SyncDbOpenOptions } from './wal-retry';

-interface LibsqlStatement {
-  run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };
+export interface SyncDbRunResult {
+  changes: number;
+  lastInsertRowid: number | bigint;
+}
+
+export interface SyncDbStatement {
+  run(...params: unknown[]): SyncDbRunResult;
  get(...params: unknown[]): unknown;
  all(...params: unknown[]): unknown[];
 }

+export interface SyncDb {
+  /** Prepare (or reuse a cached prepared statement for) the given SQL. */
+  query(sql: string): SyncDbStatement;
+  /** Execute SQL that returns no rows (pragmas, transaction control). */
+  exec(sql: string): void;
+  close(): void;
+}
+
+export type SqlRow = Record<string, unknown>;
+
+export function selectAll(db: SyncDb, sql: string, params: unknown[] = []): SqlRow[] {
+  return db.query(sql).all(...params) as SqlRow[];
+}
+
+export function selectOne(db: SyncDb, sql: string, params: unknown[] = []): SqlRow | undefined {
+  return (db.query(sql).get(...params) ?? undefined) as SqlRow | undefined;
+}
+
 interface LibsqlDatabase {
-  prepare(sql: string): LibsqlStatement;
+  prepare(sql: string): SyncDbStatement;
  exec(sql: string): unknown;
  close(): unknown;
 }

 /**
- * libsql (better-sqlite3 API) binding of the SyncDb driver for the Electron
- * app. prepare() is not cached by libsql, so query() keeps a per-connection
- * statement cache — the merge prepares a handful of statements and runs them
- * once per copied row.
+ * libsql (better-sqlite3 API) SQLite connection for the stats-sync engine.
+ * prepare() is not cached by libsql, so query() keeps a per-connection
+ * statement cache because the merge prepares a handful of statements and runs them
+ * once per copied row, so re-preparing would dominate merge time.
 */
-export const openLibsqlSyncDb: OpenSyncDb = (dbPath, options): SyncDb => {
+export function openLibsqlSyncDb(dbPath: string, options: SyncDbOpenOptions): SyncDb {
  const db = new Database(dbPath, {
    readonly: options.readonly === true,
    fileMustExist: options.create !== true,
@@ -27,22 +50,12 @@ export const openLibsqlSyncDb: OpenSyncDb = (dbPath, options): SyncDb => {
  const statements = new Map<string, SyncDbStatement>();
  return {
    query(sql: string): SyncDbStatement {
-      const cached = statements.get(sql);
-      if (cached) return cached;
-      const statement = db.prepare(sql);
-      const wrapped: SyncDbStatement = {
-        run(...params: unknown[]): SyncDbRunResult {
-          return statement.run(...params);
-        },
-        get(...params: unknown[]): unknown {
-          return statement.get(...params);
-        },
-        all(...params: unknown[]): unknown[] {
-          return statement.all(...params);
-        },
-      };
-      statements.set(sql, wrapped);
-      return wrapped;
+      let statement = statements.get(sql);
+      if (!statement) {
+        statement = db.prepare(sql);
+        statements.set(sql, statement);
+      }
+      return statement;
    },
    exec(sql: string): void {
      db.exec(sql);
@@ -52,4 +65,4 @@ export const openLibsqlSyncDb: OpenSyncDb = (dbPath, options): SyncDb => {
      db.close();
    },
  };
-};
+}
@@ -1,4 +1,4 @@
-import { selectAll, selectOne, type SqlRow, type SyncDb } from './driver';
+import { selectAll, selectOne, type SqlRow, type SyncDb } from './libsql-driver';
 import { insertRow, tableExists, type SyncMergeSummary } from './shared';

 const ANIME_COPY_COLUMNS = [
@@ -1,4 +1,4 @@
-import { selectAll, type SqlRow, type SyncDb } from './driver';
+import { selectAll, type SqlRow, type SyncDb } from './libsql-driver';
 import { nowDbTimestamp, tableExists, type SyncMergeSummary } from './shared';

 const LOCAL_DAY_EXPR = `CAST(julianday(CAST(started_at_ms AS REAL) / 1000, 'unixepoch', 'localtime') - 2440587.5 AS INTEGER)`;
@@ -1,5 +1,5 @@
 import type { LexiconResolver } from './merge-catalog';
-import { selectAll, selectOne, type SqlRow, type SyncDb } from './driver';
+import { selectAll, selectOne, type SqlRow, type SyncDb } from './libsql-driver';
 import { insertRow, nowDbTimestamp, type SyncMergeSummary } from './shared';

 const SESSION_COPY_COLUMNS = [
@@ -13,7 +13,7 @@ import {
  createEmptyMergeSummary,
  type SyncMergeSummary,
 } from './shared';
-import type { OpenSyncDb, SyncDb } from './driver';
+import { openLibsqlSyncDb, type SyncDb } from './libsql-driver';

 export type { SyncMergeSummary } from './shared';

@@ -25,11 +25,7 @@ export type { SyncMergeSummary } from './shared';
 * window is preserved on both sides. Idempotent: re-merging the same
 * snapshot is a no-op.
 */
-export function mergeSnapshotIntoDb(
-  open: OpenSyncDb,
-  localDbPath: string,
-  snapshotPath: string,
-): SyncMergeSummary {
+export function mergeSnapshotIntoDb(localDbPath: string, snapshotPath: string): SyncMergeSummary {
  if (!fs.existsSync(localDbPath)) {
    throw new Error(`Local stats database not found: ${localDbPath}`);
  }
@@ -37,10 +33,10 @@ export function mergeSnapshotIntoDb(
    throw new Error(`Snapshot database not found: ${snapshotPath}`);
  }

-  const remote = open(snapshotPath, { readonly: true });
+  const remote = openLibsqlSyncDb(snapshotPath, { readonly: true });
  let local: SyncDb;
  try {
-    local = open(localDbPath, { readwrite: true, create: false });
+    local = openLibsqlSyncDb(localDbPath, { create: false });
  } catch (error) {
    remote.close();
    throw error;
@@ -2,9 +2,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { SCHEMA_VERSION } from '../immersion-tracker/types';
-import { resolveConfigDir } from '../../../config/path-resolution';
+import { getDefaultConfigDir } from '../../../shared/setup-state';
 import { withReadonlyWalRetry } from './wal-retry';
-import { selectOne, type OpenSyncDb, type SyncDb } from './driver';
+import { openLibsqlSyncDb, selectOne, type SyncDb } from './libsql-driver';

 export { SCHEMA_VERSION };

@@ -40,7 +40,7 @@ export function tableExists(db: SyncDb, tableName: string): boolean {
  );
 }

-export function readSchemaVersion(db: SyncDb): number | null {
+function readSchemaVersion(db: SyncDb): number | null {
  if (!tableExists(db, 'imm_schema_version')) return null;
  const row = selectOne(db, 'SELECT MAX(schema_version) AS schema_version FROM imm_schema_version');
  return typeof row?.schema_version === 'number' ? row.schema_version : null;
@@ -78,14 +78,14 @@ export function insertRow(
  return Number(result.lastInsertRowid);
 }

-export function createDbSnapshot(open: OpenSyncDb, dbPath: string, outPath: string): void {
+export function createDbSnapshot(dbPath: string, outPath: string): void {
  if (!fs.existsSync(dbPath)) {
    throw new Error(`Stats database not found: ${dbPath}`);
  }
  fs.rmSync(outPath, { force: true });
  fs.mkdirSync(path.dirname(outPath), { recursive: true });
  withReadonlyWalRetry(dbPath, (options) => {
-    const db = open(dbPath, options);
+    const db = openLibsqlSyncDb(dbPath, options);
    try {
      assertMergeableSchema(db, 'Local');
      db.query('VACUUM INTO ?').run(outPath);
@@ -113,14 +113,7 @@ function isProcessAlive(pid: number): boolean {
 function statsDaemonStateCandidates(dbPath: string): string[] {
  const homeDir = os.homedir();
  const candidates = new Set<string>([path.join(path.dirname(dbPath), 'stats-daemon.json')]);
-  const configDir = resolveConfigDir({
-    platform: process.platform,
-    appDataDir: process.env.APPDATA,
-    xdgConfigHome: process.env.XDG_CONFIG_HOME,
-    homeDir,
-    existsSync: fs.existsSync,
-  });
-  candidates.add(path.join(configDir, 'stats-daemon.json'));
+  candidates.add(path.join(getDefaultConfigDir(), 'stats-daemon.json'));
  if (process.platform === 'darwin') {
    candidates.add(
      path.join(homeDir, 'Library', 'Application Support', 'SubMiner', 'stats-daemon.json'),
@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process';
+import { SYNC_CLI_FLAG } from './cli-args';

 export interface RemoteRunResult {
  status: number;
@@ -6,6 +7,12 @@ export interface RemoteRunResult {
  stderr: string;
 }

+export interface RunSshOptions {
+  batchMode?: boolean;
+  connectTimeoutSeconds?: number;
+  timeoutMs?: number;
+}
+
 /**
 * ssh/scp have no `--` terminator for the destination, so a host that starts
 * with `-` (e.g. `-oProxyCommand=...`) is parsed as an option. Reject those
@@ -22,11 +29,22 @@ export function assertSafeSshHost(host: string): void {
 * can still read from the terminal; stdout/stderr are captured for callers
 * that need actionable remote failure messages.
 */
-export function runSsh(host: string, remoteCommand: string): RemoteRunResult {
+export function runSsh(
+  host: string,
+  remoteCommand: string,
+  options: RunSshOptions = {},
+): RemoteRunResult {
  assertSafeSshHost(host);
-  const result = spawnSync('ssh', [host, remoteCommand], {
+  const args: string[] = [];
+  if (options.batchMode) args.push('-o', 'BatchMode=yes');
+  if (options.connectTimeoutSeconds !== undefined) {
+    args.push('-o', `ConnectTimeout=${options.connectTimeoutSeconds}`);
+  }
+  args.push(host, remoteCommand);
+  const result = spawnSync('ssh', args, {
    encoding: 'utf8',
    stdio: ['inherit', 'pipe', 'pipe'],
+    timeout: options.timeoutMs,
  });
  if (result.error) {
    throw new Error(`Failed to run ssh: ${(result.error as Error).message}`);
@@ -74,7 +92,7 @@ export function shellQuote(value: string): string {

 /**
 * The shell that Windows OpenSSH hands remote commands to (cmd.exe by
- * default, PowerShell when DefaultShell is changed) — it decides quoting,
+ * default, PowerShell when DefaultShell is changed); it decides quoting,
 * environment-variable expansion, and which SubMiner install paths to probe.
 */
 export type RemoteShellFlavor = 'posix' | 'windows-cmd' | 'windows-powershell';
@@ -87,7 +105,7 @@ export type RemoteShellFlavor = 'posix' | 'windows-cmd' | 'windows-powershell';
 */
 export function detectRemoteShellFlavor(
  host: string,
-  runRemote: typeof runSsh = runSsh,
+  runRemote: (host: string, remoteCommand: string) => RemoteRunResult,
 ): RemoteShellFlavor {
  const posixProbe = runRemote(host, 'uname -s');
  if (posixProbe.status === 0 && posixProbe.stdout.trim().length > 0) return 'posix';
@@ -127,15 +145,10 @@ const REMOTE_RUNTIME_PATH =
  'PATH="$HOME/.local/bin:$HOME/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:$PATH"';

 // The Electron app answers the same launcher-style `sync ...` argv when
-// invoked with --sync-cli, so a remote machine only needs the app installed;
-// the command-line launcher is one candidate, not a requirement.
-const APP_SYNC_CLI_FLAG = '--sync-cli';
-
-interface RemoteCandidate {
-  invocation: string;
-}
-
-function defaultRemoteCandidates(flavor: RemoteShellFlavor): RemoteCandidate[] {
+// invoked with --sync-cli (SYNC_CLI_FLAG), so a remote machine only needs the
+// app installed; the command-line launcher is one candidate, not a
+// requirement. Each candidate is the remote invocation to probe, in order.
+function defaultRemoteCandidates(flavor: RemoteShellFlavor): string[] {
  if (flavor === 'windows-cmd' || flavor === 'windows-powershell') {
    // cmd.exe expands %VAR% inside double quotes; PowerShell needs $env: and
    // the & call operator to run a quoted path.
@@ -149,30 +162,30 @@ function defaultRemoteCandidates(flavor: RemoteShellFlavor): RemoteCandidate[] {
        : `& "$env:LOCALAPPDATA\\Programs\\SubMiner\\SubMiner.exe"`;
    return [
      // Command-line launcher shim on PATH or in its default install dir.
-      { invocation: 'subminer' },
-      { invocation: launcherShim },
+      'subminer',
+      launcherShim,
      // The app binary itself in sync-CLI mode (default NSIS install dir).
-      { invocation: `${appInstall} ${APP_SYNC_CLI_FLAG}` },
-      { invocation: `SubMiner ${APP_SYNC_CLI_FLAG}` },
+      `${appInstall} ${SYNC_CLI_FLAG}`,
+      `SubMiner ${SYNC_CLI_FLAG}`,
    ];
  }
  return [
    // Command-line launcher (bun script) on PATH or in its default install dir.
-    { invocation: 'subminer' },
-    { invocation: '~/.local/bin/subminer' },
+    'subminer',
+    '~/.local/bin/subminer',
    // The app binary itself in sync-CLI mode.
-    { invocation: `SubMiner ${APP_SYNC_CLI_FLAG}` },
-    { invocation: `/Applications/SubMiner.app/Contents/MacOS/SubMiner ${APP_SYNC_CLI_FLAG}` },
-    { invocation: `~/Applications/SubMiner.app/Contents/MacOS/SubMiner ${APP_SYNC_CLI_FLAG}` },
+    `SubMiner ${SYNC_CLI_FLAG}`,
+    `/Applications/SubMiner.app/Contents/MacOS/SubMiner ${SYNC_CLI_FLAG}`,
+    `~/Applications/SubMiner.app/Contents/MacOS/SubMiner ${SYNC_CLI_FLAG}`,
  ];
 }

-function preferredCandidates(flavor: RemoteShellFlavor, preferred: string): RemoteCandidate[] {
+function preferredCandidates(flavor: RemoteShellFlavor, preferred: string): string[] {
  const quoted = quoteForRemoteShell(flavor, preferred);
  const invocation = flavor === 'windows-powershell' ? `& ${quoted}` : quoted;
  // App binaries also answer plain --help by opening the GUI-oriented help
  // path, so probe the sync-CLI shape first.
-  return [{ invocation: `${invocation} ${APP_SYNC_CLI_FLAG}` }, { invocation }];
+  return [`${invocation} ${SYNC_CLI_FLAG}`, invocation];
 }

 /**
@@ -193,8 +206,7 @@ export function resolveRemoteSubminerCommand(
    ? preferredCandidates(flavor, preferred)
    : defaultRemoteCandidates(flavor);
  for (const candidate of candidates) {
-    const command =
-      flavor === 'posix' ? `${REMOTE_RUNTIME_PATH} ${candidate.invocation}` : candidate.invocation;
+    const command = flavor === 'posix' ? `${REMOTE_RUNTIME_PATH} ${candidate}` : candidate;
    const probe = runRemote(
      host,
      flavor === 'posix' ? `${command} --help >/dev/null 2>&1` : `${command} --help`,
@@ -14,7 +14,6 @@ import {
 function makeContext(overrides: Partial<SyncFlowContext['args']> = {}): SyncFlowContext {
  return {
    args: {
-      sync: true,
      syncHost: '',
      syncSnapshotPath: '',
      syncMergePath: '',
@@ -43,17 +42,12 @@ function makeDeps(overrides: Partial<SyncFlowDeps> = {}): SyncFlowDeps {
  return {
    createDbSnapshot: () => {},
    mergeSnapshotIntoDb: () => createEmptyMergeSummary(),
-    formatMergeSummary: () => 'summary',
    findLiveStatsDaemonPid: () => null,
    assertSafeSshHost: () => {},
    detectRemoteShellFlavor: () => 'posix',
    resolveRemoteSubminerCommand: () => 'subminer',
    runScp: () => {},
    runSsh: () => ok(),
-    fail: (message: string): never => {
-      throw new Error(message);
-    },
-    log: () => {},
    canConnectUnixSocket: async () => false,
    realpathSync: (candidate) => candidate,
    mkdtempSync: (prefix) => fs.mkdtempSync(prefix),
@@ -64,7 +58,6 @@ function makeDeps(overrides: Partial<SyncFlowDeps> = {}): SyncFlowDeps {
    emitEvent: () => {},
    recordHostSyncResult: () => {},
    resolveDefaultDbPath: () => '/tracker.sqlite',
-    resolvePath: (value) => value,
    ...overrides,
  };
 }
@@ -128,12 +121,9 @@ test('runSyncFlow dispatches snapshot, merge, host, and missing-target modes', a
    },
  });

-  assert.equal(
-    await runSyncFlow(
-      makeContext({ syncDbPath: '/tmp/local.sqlite', syncSnapshotPath: '/tmp/out.sqlite' }),
-      deps,
-    ),
-    true,
+  await runSyncFlow(
+    makeContext({ syncDbPath: '/tmp/local.sqlite', syncSnapshotPath: '/tmp/out.sqlite' }),
+    deps,
  );
  assert.ok(calls.includes('snapshot:/tmp/local.sqlite->/tmp/out.sqlite'));
  assert.ok(
@@ -154,8 +144,6 @@ test('runSyncFlow dispatches snapshot, merge, host, and missing-target modes', a
    () => runSyncFlow(makeContext({ syncDbPath: '/tmp/local.sqlite' }), deps),
    /sync requires a host, --snapshot <file>, or --merge <file>/,
  );
-
-  assert.equal(await runSyncFlow(makeContext({ sync: false }), deps), false);
 });

 function makeHostDeps(calls: string[], overrides: Partial<SyncFlowDeps> = {}): SyncFlowDeps {
@@ -262,13 +250,24 @@ test('runHostSync pull only snapshots remotely and merges locally', async () =>

 test('runSyncFlow --json emits NDJSON progress events and a final result', async () => {
  const lines: string[] = [];
+  const remoteSummary = {
+    ...createEmptyMergeSummary(),
+    sessionsMerged: 2,
+    videosAdded: 1,
+  };
  const deps = makeHostDeps([], {
    consoleLog: (line) => {
      lines.push(line);
    },
    runSsh: (_host, command) => {
      if (command.includes(' sync --make-temp')) return ok('/tmp/subminer-sync-remote\n');
-      if (command.includes(' sync --merge ')) return ok('remote summary text\n');
+      if (command.includes(' sync --merge ')) {
+        assert.match(command, / --json(?: |$)/);
+        return ok(
+          `${JSON.stringify({ type: 'merge-summary', target: 'local', summary: remoteSummary })}\n` +
+            `${JSON.stringify({ type: 'result', ok: true, error: null })}\n`,
+        );
+      }
      return ok();
    },
  });
@@ -281,10 +280,9 @@ test('runSyncFlow --json emits NDJSON progress events and a final result', async
  const events = lines.map((line) => JSON.parse(line));
  assert.ok(events.some((event) => event.type === 'stage' && event.stage === 'snapshot-local'));
  assert.ok(events.some((event) => event.type === 'merge-summary' && event.target === 'local'));
-  assert.ok(
-    events.some(
-      (event) => event.type === 'remote-output' && event.text.includes('remote summary text'),
-    ),
+  assert.deepEqual(
+    events.find((event) => event.type === 'merge-summary' && event.target === 'remote'),
+    { type: 'merge-summary', target: 'remote', summary: remoteSummary },
  );
  assert.deepEqual(events[events.length - 1], { type: 'result', ok: true, error: null });
 });
@@ -351,11 +349,17 @@ test('runHostSync records host sync results for saved-host bookkeeping', async (

 test('runCheckMode --json reports ssh and remote SubMiner status', async () => {
  const lines: string[] = [];
+  const sshOptions: unknown[] = [];
  const deps = makeDeps({
    consoleLog: (line) => {
      lines.push(line);
    },
-    runSsh: (_host, command) => {
+    resolveRemoteSubminerCommand: (host, _preferred, _flavor, runRemote) => {
+      runRemote!(host, 'subminer --help');
+      return 'subminer';
+    },
+    runSsh: (_host, command, options) => {
+      sshOptions.push(options);
      if (command.includes('--version')) return ok('SubMiner 0.18.0\n');
      return ok('subminer-check-ok\n');
    },
@@ -380,6 +384,14 @@ test('runCheckMode --json reports ssh and remote SubMiner status', async () => {
  assert.equal(check.remoteVersion, 'SubMiner 0.18.0');
  assert.equal(check.ok, true);
  assert.equal(check.error, null);
+  assert.equal(sshOptions.length, 3);
+  assert.ok(
+    sshOptions.every(
+      (options) =>
+        JSON.stringify(options) ===
+        JSON.stringify({ batchMode: true, connectTimeoutSeconds: 10, timeoutMs: 15_000 }),
+    ),
+  );

  const failLines: string[] = [];
  await assert.rejects(() =>
@@ -1,12 +1,16 @@
 import os from 'node:os';
 import path from 'node:path';
+import { formatMergeSummary } from './merge';
 import { quoteForRemoteShell } from './ssh';
-import type { RemoteRunResult, RemoteShellFlavor } from './ssh';
-import type { SyncMergeSummary, SyncProgressEvent } from '../../../shared/sync/sync-events';
+import type { RemoteRunResult, RemoteShellFlavor, RunSshOptions } from './ssh';
+import {
+  parseSyncProgressLine,
+  type SyncMergeSummary,
+  type SyncProgressEvent,
+} from '../../../shared/sync/sync-events';
 import type { SyncResultStatus } from '../../../shared/sync/sync-hosts-store';

 export interface SyncFlowArgs {
-  sync: boolean;
  syncHost: string;
  syncSnapshotPath: string;
  syncMergePath: string;
@@ -27,14 +31,14 @@ export interface SyncFlowContext {
 }

 /**
- * Everything the sync flow touches outside plain computation. The launcher
- * binds these to bun:sqlite-backed engine functions and its own logger; the
- * app's --sync-cli mode binds libsql and console output. Tests stub freely.
+ * Process/IO seams the sync flow needs stubbed in tests: SSH/scp, the DB
+ * snapshot/merge engine, filesystem, and progress/bookkeeping output. The
+ * app's --sync-cli mode (src/main/sync-cli.ts) provides the only production
+ * binding; pure helpers are imported directly.
 */
 export interface SyncFlowDeps {
  createDbSnapshot: (dbPath: string, outPath: string) => void;
  mergeSnapshotIntoDb: (localDbPath: string, snapshotPath: string) => SyncMergeSummary;
-  formatMergeSummary: (summary: SyncMergeSummary) => string;
  findLiveStatsDaemonPid: (dbPath: string) => number | null;
  assertSafeSshHost: (host: string) => void;
  detectRemoteShellFlavor: (
@@ -45,11 +49,10 @@ export interface SyncFlowDeps {
    host: string,
    preferred: string | null,
    flavor: RemoteShellFlavor,
+    runRemote?: (host: string, remoteCommand: string) => RemoteRunResult,
  ) => string;
  runScp: (from: string, to: string) => void;
-  runSsh: (host: string, remoteCommand: string) => RemoteRunResult;
-  fail: (message: string) => never;
-  log: (level: string, configuredLevel: string, message: string) => void;
+  runSsh: (host: string, remoteCommand: string, options?: RunSshOptions) => RemoteRunResult;
  canConnectUnixSocket: (socketPath: string) => Promise<boolean>;
  realpathSync: (candidate: string) => string;
  mkdtempSync: (prefix: string) => string;
@@ -60,23 +63,27 @@ export interface SyncFlowDeps {
  emitEvent: (event: SyncProgressEvent) => void;
  recordHostSyncResult: (host: string, status: SyncResultStatus, detail: string | null) => void;
  resolveDefaultDbPath: () => string;
-  resolvePath: (value: string) => string;
+}
+
+/** Expand a leading `~` (as ssh users write paths) and make the path absolute. */
+function resolveCliPath(input: string): string {
+  return input.startsWith('~') ? path.join(os.homedir(), input.slice(1)) : path.resolve(input);
 }

 /**
 * Prefix shared by every sync temp dir, local or remote. Remote temp dirs are
 * created and removed by the remote SubMiner itself (sync --make-temp /
 * --remove-temp) so the flow never depends on mktemp/rm existing in the
- * remote shell — that is what makes Windows remotes work.
+ * remote shell. This is what makes Windows remotes work.
 */
-export const SYNC_TEMP_PREFIX = 'subminer-sync-';
+const SYNC_TEMP_PREFIX = 'subminer-sync-';

-export function makeSyncTempDir(mkdtempSync: SyncFlowDeps['mkdtempSync']): string {
+function makeSyncTempDir(mkdtempSync: SyncFlowDeps['mkdtempSync']): string {
  return mkdtempSync(path.join(os.tmpdir(), SYNC_TEMP_PREFIX));
 }

 /** Only dirs directly under os.tmpdir() with the sync prefix may be removed. */
-export function assertRemovableSyncTempDir(target: string): string {
+function assertRemovableSyncTempDir(target: string): string {
  const resolved = path.resolve(target.trim());
  const normalizeCase = (value: string) =>
    process.platform === 'win32' ? value.toLowerCase() : value;
@@ -88,18 +95,18 @@ export function assertRemovableSyncTempDir(target: string): string {
  return resolved;
 }

-export function runMakeTempMode(deps: SyncFlowDeps): void {
+function runMakeTempMode(deps: SyncFlowDeps): void {
  deps.consoleLog(makeSyncTempDir(deps.mkdtempSync));
 }

-export function runRemoveTempMode(context: SyncFlowContext, deps: SyncFlowDeps): void {
+function runRemoveTempMode(context: SyncFlowContext, deps: SyncFlowDeps): void {
  const target = assertRemovableSyncTempDir(context.args.syncRemoveTempPath);
  deps.rmSync(target, { recursive: true, force: true });
 }

-export function resolveSyncDbPath(context: SyncFlowContext, deps: SyncFlowDeps): string {
+function resolveSyncDbPath(context: SyncFlowContext, deps: SyncFlowDeps): string {
  const override = context.args.syncDbPath.trim();
-  return override ? deps.resolvePath(override) : deps.resolveDefaultDbPath();
+  return override ? resolveCliPath(override) : deps.resolveDefaultDbPath();
 }

 function isTrackerDb(dbPath: string, deps: SyncFlowDeps): boolean {
@@ -122,12 +129,12 @@ export async function ensureTrackerQuiescentFlow(
  if (!isTrackerDb(dbPath, deps)) return;
  const daemonPid = deps.findLiveStatsDaemonPid(dbPath);
  if (daemonPid !== null) {
-    deps.fail(
+    throw new Error(
      `The SubMiner stats server is running (pid ${daemonPid}). Stop it with "subminer stats -s" (or close SubMiner) before syncing, or pass --force.`,
    );
  }
  if (context.mpvSocketPath && (await deps.canConnectUnixSocket(context.mpvSocketPath))) {
-    deps.fail(
+    throw new Error(
      `An mpv/SubMiner session appears to be running (socket ${context.mpvSocketPath}). Close it before syncing, or pass --force.`,
    );
  }
@@ -135,7 +142,7 @@ export async function ensureTrackerQuiescentFlow(

 // In --json mode every line on stdout is an NDJSON event: human console output
 // is silenced and events are written through the original console logger.
-export function withJsonEvents(deps: SyncFlowDeps): SyncFlowDeps {
+function withJsonEvents(deps: SyncFlowDeps): SyncFlowDeps {
  const writeLine = deps.consoleLog;
  return {
    ...deps,
@@ -145,13 +152,13 @@ export function withJsonEvents(deps: SyncFlowDeps): SyncFlowDeps {
  };
 }

-export async function runSnapshotMode(
+async function runSnapshotMode(
  context: SyncFlowContext,
  dbPath: string,
  deps: SyncFlowDeps,
 ): Promise<void> {
  await deps.ensureTrackerQuiescent(context, dbPath);
-  const outPath = deps.resolvePath(context.args.syncSnapshotPath);
+  const outPath = resolveCliPath(context.args.syncSnapshotPath);
  deps.emitEvent({
    type: 'stage',
    stage: 'snapshot-local',
@@ -162,13 +169,13 @@ export async function runSnapshotMode(
  deps.consoleLog(outPath);
 }

-export async function runMergeMode(
+async function runMergeMode(
  context: SyncFlowContext,
  dbPath: string,
  deps: SyncFlowDeps,
 ): Promise<void> {
  await deps.ensureTrackerQuiescent(context, dbPath);
-  const snapshotPath = deps.resolvePath(context.args.syncMergePath);
+  const snapshotPath = resolveCliPath(context.args.syncMergePath);
  deps.emitEvent({
    type: 'stage',
    stage: 'merge-local',
@@ -176,7 +183,7 @@ export async function runMergeMode(
  });
  const summary = deps.mergeSnapshotIntoDb(dbPath, snapshotPath);
  deps.emitEvent({ type: 'merge-summary', target: 'local', summary });
-  deps.consoleLog(deps.formatMergeSummary(summary));
+  deps.consoleLog(formatMergeSummary(summary));
 }

 function formatHostSyncDetail(
@@ -198,17 +205,28 @@ export async function runCheckMode(context: SyncFlowContext, deps: SyncFlowDeps)
  let remoteVersion: string | null = null;
  let error: string | null = null;

-  const probe = deps.runSsh(host, 'echo subminer-check-ok');
+  const runCheck = (checkHost: string, command: string) =>
+    deps.runSsh(checkHost, command, {
+      batchMode: true,
+      connectTimeoutSeconds: 10,
+      timeoutMs: 15_000,
+    });
+  const probe = runCheck(host, 'echo subminer-check-ok');
  const sshOk = probe.status === 0 && probe.stdout.includes('subminer-check-ok');
  if (!sshOk) {
    error = formatRemoteRunError(`Could not reach ${host} over SSH.`, probe);
  } else {
    deps.consoleLog('SSH connection: ok');
    try {
-      const flavor = deps.detectRemoteShellFlavor(host, deps.runSsh);
+      const flavor = deps.detectRemoteShellFlavor(host, runCheck);
      if (flavor !== 'posix') deps.consoleLog(`Remote platform: Windows (${flavor})`);
-      remoteCommand = deps.resolveRemoteSubminerCommand(host, args.syncRemoteCmd || null, flavor);
-      const version = deps.runSsh(host, `${remoteCommand} --version`);
+      remoteCommand = deps.resolveRemoteSubminerCommand(
+        host,
+        args.syncRemoteCmd || null,
+        flavor,
+        runCheck,
+      );
+      const version = runCheck(host, `${remoteCommand} --version`);
      remoteVersion = version.status === 0 ? version.stdout.trim() || null : null;
      deps.consoleLog(
        `Remote subminer: ${remoteCommand}${remoteVersion ? ` (${remoteVersion})` : ''}`,
@@ -262,6 +280,14 @@ function parseRemoteTempDir(stdout: string): string {
  return path.posix.basename(candidate).startsWith(SYNC_TEMP_PREFIX) ? candidate : '';
 }

+function parseRemoteMergeSummary(stdout: string): SyncMergeSummary | null {
+  for (const line of stdout.split('\n')) {
+    const event = parseSyncProgressLine(line);
+    if (event?.type === 'merge-summary' && event.target === 'local') return event.summary;
+  }
+  return null;
+}
+
 function formatRemoteRunError(message: string, run: RemoteRunResult): string {
  const stderr = run.stderr.trim();
  return stderr ? `${message}\n${stderr}` : message;
@@ -284,7 +310,9 @@ export async function runHostSync(
  const flavor = deps.detectRemoteShellFlavor(host, deps.runSsh);
  const remoteCmd = deps.resolveRemoteSubminerCommand(host, args.syncRemoteCmd || null, flavor);
  const quote = (value: string) => quoteForRemoteShell(flavor, value);
-  deps.log('debug', args.logLevel, `Remote subminer command (${flavor}): ${remoteCmd}`);
+  if (args.logLevel === 'debug') {
+    console.error(`Remote subminer command (${flavor}): ${remoteCmd}`);
+  }

  const localTmpDir = makeSyncTempDir(deps.mkdtempSync);
  let remoteTmpDir = '';
@@ -353,7 +381,7 @@ export async function runHostSync(
      const summary = deps.mergeSnapshotIntoDb(dbPath, pulledSnapshot);
      pulledSummary = summary;
      deps.emitEvent({ type: 'merge-summary', target: 'local', summary });
-      deps.consoleLog(deps.formatMergeSummary(summary));
+      deps.consoleLog(formatMergeSummary(summary));
    }

    if (shouldPush) {
@@ -366,10 +394,13 @@ export async function runHostSync(
      await deps.ensureTrackerQuiescent(context, dbPath);
      const mergeRun = deps.runSsh(
        host,
-        `${remoteCmd} sync --merge ${quote(incomingSnapshot)}${forceFlag}`,
+        `${remoteCmd} sync --merge ${quote(incomingSnapshot)}${forceFlag}${args.syncJson ? ' --json' : ''}`,
      );
      deps.writeStdout(mergeRun.stdout);
-      if (mergeRun.stdout.trim()) {
+      const remoteSummary = args.syncJson ? parseRemoteMergeSummary(mergeRun.stdout) : null;
+      if (remoteSummary) {
+        deps.emitEvent({ type: 'merge-summary', target: 'remote', summary: remoteSummary });
+      } else if (mergeRun.stdout.trim()) {
        deps.emitEvent({ type: 'remote-output', text: mergeRun.stdout });
      }
      if (mergeRun.status !== 0) {
@@ -413,34 +444,29 @@ export async function runHostSync(
 export async function runSyncFlow(
  context: SyncFlowContext,
  inputDeps: SyncFlowDeps,
-): Promise<boolean> {
+): Promise<void> {
  let deps = inputDeps;
  const { args } = context;
-  if (!args.sync) return false;
  if (args.syncJson) deps = withJsonEvents(deps);

  try {
    if (args.syncMakeTemp) {
      runMakeTempMode(deps);
-      if (args.syncJson) deps.emitEvent({ type: 'result', ok: true, error: null });
-      return true;
-    }
-    if (args.syncRemoveTempPath) {
+    } else if (args.syncRemoveTempPath) {
      runRemoveTempMode(context, deps);
-      if (args.syncJson) deps.emitEvent({ type: 'result', ok: true, error: null });
-      return true;
-    }
-    const dbPath = resolveSyncDbPath(context, deps);
-    if (args.syncCheck) {
-      await runCheckMode(context, deps);
-    } else if (args.syncSnapshotPath) {
-      await runSnapshotMode(context, dbPath, deps);
-    } else if (args.syncMergePath) {
-      await runMergeMode(context, dbPath, deps);
-    } else if (args.syncHost) {
-      await runHostSync(context, dbPath, deps);
    } else {
-      deps.fail('sync requires a host, --snapshot <file>, or --merge <file>.');
+      const dbPath = resolveSyncDbPath(context, deps);
+      if (args.syncCheck) {
+        await runCheckMode(context, deps);
+      } else if (args.syncSnapshotPath) {
+        await runSnapshotMode(context, dbPath, deps);
+      } else if (args.syncMergePath) {
+        await runMergeMode(context, dbPath, deps);
+      } else if (args.syncHost) {
+        await runHostSync(context, dbPath, deps);
+      } else {
+        throw new Error('sync requires a host, --snapshot <file>, or --merge <file>.');
+      }
    }
  } catch (error) {
    if (args.syncJson) {
@@ -453,5 +479,4 @@ export async function runSyncFlow(
    throw error;
  }
  if (args.syncJson) deps.emitEvent({ type: 'result', ok: true, error: null });
-  return true;
 }
@@ -1,5 +1,16 @@
 import fs from 'node:fs';
-import type { SyncDbOpenOptions } from './driver';
+
+export interface SyncDbOpenOptions {
+  readonly?: boolean;
+  /**
+   * Read-write open. The libsql opener treats "not readonly" as read-write,
+   * but the launcher's bun:sqlite history reader passes these options straight
+   * to `new Database(...)`, where an explicit readwrite flag is what prevents
+   * bun from defaulting to readwrite+create. Keep it.
+   */
+  readwrite?: boolean;
+  create?: boolean;
+}

 /**
 * Opening a WAL-mode SQLite database strictly read-only fails when the -shm
@@ -30,7 +30,7 @@ import {
 } from './main/runtime/first-run-setup-plugin';
 import { createWindowsMpvLaunchDeps, launchWindowsMpv } from './main/runtime/windows-mpv-launch';
 import { runStatsDaemonControlFromProcess } from './stats-daemon-entry';
-import { runSyncCliFromProcess, shouldHandleSyncCliAtEntry } from './main/sync-cli';
+import { handleSyncCliAtEntry } from './main/sync-cli';
 import { createFatalErrorReporter, registerFatalErrorHandlers } from './main/fatal-error';
 import { buildMpvLoggingArgs } from './shared/mpv-logging-args';
 import {
@@ -224,11 +224,7 @@ async function forwardStartupArgvViaAppControlIfAvailable(): Promise<boolean> {
 async function runEntryProcess(): Promise<void> {
  // Headless sync CLI: must run first (its own --help/--version handling) and
  // exit before app.whenReady() so it works over SSH with no display server.
-  if (shouldHandleSyncCliAtEntry(process.argv, process.env)) {
-    const exitCode = await runSyncCliFromProcess(process.argv, app.getVersion());
-    app.exit(exitCode);
-    return;
-  }
+  if (await handleSyncCliAtEntry(process.argv, process.env, app.getVersion())) return;

  if (shouldHandleHelpOnlyAtEntry(process.argv, process.env)) {
    const sanitizedEnv = sanitizeHelpEnv(process.env);
@@ -536,6 +536,7 @@ import { createOpenConfigSettingsWindowHandler } from './main/runtime/config-set
 import { createSyncUiRuntime } from './main/runtime/sync-ui-runtime';
 import { createSyncAutoScheduler } from './main/runtime/sync-auto-scheduler';
 import { resolveSyncLauncherCommand, runSyncLauncher } from './main/runtime/sync-launcher-client';
+import { getSyncHostsPath } from './shared/sync/sync-hosts-store';
 import { shouldSuppressVisibleOverlayRaiseForSeparateWindow } from './main/runtime/settings-window-z-order';
 import {
  isSameYoutubeMediaPath,
@@ -2245,13 +2246,18 @@ const openSyncUiWindowHandler = createOpenConfigSettingsWindowHandler({
  settingsHtmlPath: path.join(__dirname, 'syncui', 'index.html'),
  promoteSettingsWindowAboveOverlay: (window) =>
    promoteSettingsWindowAboveOverlay(window as BrowserWindow),
+  onClosed: () => {
+    // requestAppQuit (not app.quit) so the forced-exit fallback covers a
+    // stalled quit; a standalone sync window is the app's only reason to live.
+    if (appState.initialArgs?.syncWindow) requestAppQuit();
+  },
  log: (message) => logger.error(message),
 });
 const openSyncUiWindow = () => openSyncUiWindowHandler();

 const syncUiRuntime = createSyncUiRuntime({
  ipcMain,
-  hostsFilePath: path.join(USER_DATA_PATH, 'sync-hosts.json'),
+  hostsFilePath: getSyncHostsPath(USER_DATA_PATH),
  snapshotsDir: path.join(os.tmpdir(), 'subminer-db-snapshots'),
  getDbPath: () => {
    const configured = getResolvedConfig().immersionTracking?.dbPath?.trim();
@@ -2284,13 +2290,11 @@ const syncUiRuntime = createSyncUiRuntime({
 });
 syncUiRuntime.registerHandlers();

-// Auto-sync only runs while no mpv session or app-owned stats server could be
-// writing the immersion database; the launcher's quiescence guard covers
-// writers this process does not know about.
+// Live sync uses a consistent WAL snapshot plus a transactional merge, and it
+// skips unfinished sessions, so resident stats writers do not block scheduling.
 const syncAutoScheduler = createSyncAutoScheduler({
  readState: () => syncUiRuntime.readState(),
  isRunning: () => syncUiRuntime.isRunning(),
-  canAutoSync: () => appState.mpvClient === null && appState.statsServer === null,
  triggerHostSync: (host, direction) => {
    void syncUiRuntime.runHostSync({ host, direction }, { notify: true });
  },
@@ -45,13 +45,14 @@ test('createOpenConfigSettingsWindowHandler creates window and clears closed sta
    createSettingsWindow: () => created,
    settingsHtmlPath: '/tmp/settings.html',
    promoteSettingsWindowAboveOverlay: () => calls.push('promote'),
+    onClosed: () => calls.push('on-closed'),
  });

  assert.equal(open(), true);
  assert.deepEqual(calls, ['load:/tmp/settings.html', 'set:window', 'show', 'focus', 'promote']);
  assert.ok(handlers.closed);
  handlers.closed();
-  assert.equal(calls.at(-1), 'set:null');
+  assert.deepEqual(calls.slice(-2), ['set:null', 'on-closed']);
 });

 test('createOpenConfigSettingsWindowHandler clears failed load window state', async () => {
@@ -13,6 +13,7 @@ export interface OpenConfigSettingsWindowDeps<TWindow extends ConfigSettingsWind
  createSettingsWindow(): TWindow;
  settingsHtmlPath: string;
  promoteSettingsWindowAboveOverlay?: (window: TWindow) => void;
+  onClosed?: () => void;
  log?: (message: string) => void;
 }

@@ -42,6 +43,7 @@ export function createOpenConfigSettingsWindowHandler<TWindow extends ConfigSett
    deps.setSettingsWindow(window);
    window.on('closed', () => {
      deps.setSettingsWindow(null);
+      deps.onClosed?.();
    });
    showAndFocus(window);
    return true;
@@ -22,7 +22,6 @@ test('tick triggers a due auto-sync host with its saved direction', () => {
  const scheduler = createSyncAutoScheduler({
    readState: () => state,
    isRunning: () => false,
-    canAutoSync: () => true,
    triggerHostSync: (host, direction) => triggered.push({ host, direction }),
    nowMs: () => 100 * 60_000,
  });
@@ -31,6 +30,20 @@ test('tick triggers a due auto-sync host with its saved direction', () => {
  assert.deepEqual(triggered, [{ host: 'auto-box', direction: 'pull' }]);
 });

+test('tick does not require the resident app and stats writer to stop', () => {
+  const state = makeState();
+  const triggered: string[] = [];
+  const scheduler = createSyncAutoScheduler({
+    readState: () => state,
+    isRunning: () => false,
+    triggerHostSync: (host) => triggered.push(host),
+    nowMs: () => 100 * 60_000,
+  });
+
+  assert.doesNotThrow(() => scheduler.tick());
+  assert.deepEqual(triggered, ['auto-box']);
+});
+
 test('tick skips hosts synced more recently than the interval', () => {
  let state = makeState();
  state = recordSyncResult(state, 'auto-box', {
@@ -42,7 +55,6 @@ test('tick skips hosts synced more recently than the interval', () => {
  const scheduler = createSyncAutoScheduler({
    readState: () => state,
    isRunning: () => false,
-    canAutoSync: () => true,
    triggerHostSync: (host) => triggered.push(host),
    nowMs: () => 100 * 60_000, // 10 minutes later, default interval 30
  });
@@ -51,27 +63,17 @@ test('tick skips hosts synced more recently than the interval', () => {
  assert.deepEqual(triggered, []);
 });

-test('tick does nothing while a run is active or auto sync is blocked', () => {
+test('tick does nothing while a run is active', () => {
  const state = makeState();
  const triggered: string[] = [];
  const running = createSyncAutoScheduler({
    readState: () => state,
    isRunning: () => true,
-    canAutoSync: () => true,
    triggerHostSync: (host) => triggered.push(host),
    nowMs: () => 100 * 60_000,
  });
  running.tick();

-  const blocked = createSyncAutoScheduler({
-    readState: () => state,
-    isRunning: () => false,
-    canAutoSync: () => false,
-    triggerHostSync: (host) => triggered.push(host),
-    nowMs: () => 100 * 60_000,
-  });
-  blocked.tick();
-
  assert.deepEqual(triggered, []);
 });

@@ -82,7 +84,6 @@ test('tick triggers at most one host per tick', () => {
  const scheduler = createSyncAutoScheduler({
    readState: () => state,
    isRunning: () => false,
-    canAutoSync: () => true,
    triggerHostSync: (host) => triggered.push(host),
    nowMs: () => 100 * 60_000,
  });
@@ -98,7 +99,6 @@ test('tick logs a synchronous trigger failure and remains usable', () => {
  const scheduler = createSyncAutoScheduler({
    readState: () => state,
    isRunning: () => false,
-    canAutoSync: () => true,
    triggerHostSync: () => {
      attempts += 1;
      throw new Error('spawn exploded');
@@ -120,7 +120,6 @@ test('start/stop manage the interval timer', () => {
  const scheduler = createSyncAutoScheduler({
    readState: () => state,
    isRunning: () => false,
-    canAutoSync: () => true,
    triggerHostSync: () => {},
    nowMs: () => 0,
    setIntervalFn: ((): NodeJS.Timeout => {
@@ -3,7 +3,6 @@ import type { SyncDirection, SyncHostsState } from '../../shared/sync/sync-hosts
 export interface SyncAutoSchedulerDeps {
  readState: () => SyncHostsState;
  isRunning: () => boolean;
-  canAutoSync: () => boolean;
  triggerHostSync: (host: string, direction: SyncDirection) => void;
  nowMs: () => number;
  log?: (message: string) => void;
@@ -18,7 +17,7 @@ export function createSyncAutoScheduler(deps: SyncAutoSchedulerDeps) {
  let timer: NodeJS.Timeout | null = null;

  function tick(): void {
-    if (deps.isRunning() || !deps.canAutoSync()) return;
+    if (deps.isRunning()) return;
    const state = deps.readState();
    const intervalMs = state.autoSyncIntervalMinutes * 60_000;
    const now = deps.nowMs();
@@ -2,7 +2,11 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { EventEmitter } from 'node:events';
 import type { SyncProgressEvent } from '../../shared/sync/sync-events';
-import { runSyncLauncher, type SyncLauncherSpawn } from './sync-launcher-client';
+import {
+  runSyncLauncher,
+  sanitizeSyncLauncherEnv,
+  type SyncLauncherSpawn,
+} from './sync-launcher-client';

 class FakeChild extends EventEmitter {
  stdout = new EventEmitter();
@@ -51,6 +55,52 @@ test('runSyncLauncher parses NDJSON events across chunk boundaries', async () =>
  assert.deepEqual(result, { ok: true, error: null });
 });

+test('runSyncLauncher preserves multibyte characters split across chunks', async () => {
+  const { spawn, children } = makeSpawn();
+  const events: SyncProgressEvent[] = [];
+  const handle = runSyncLauncher({
+    command: ['subminer'],
+    args: ['sync', 'media-box', '--json'],
+    onEvent: (event) => events.push(event),
+    spawn,
+  });
+
+  const child = children[0]!;
+  const line = Buffer.from('{"type":"result","ok":false,"error":"進捗の同期に失敗"}\n');
+  // Split mid-character: the boundary lands inside a multibyte code point.
+  const boundary = line.indexOf(Buffer.from('進')) + 1;
+  child.stdout.emit('data', line.subarray(0, boundary));
+  child.stdout.emit('data', line.subarray(boundary));
+  child.emit('close', 1, null);
+
+  const result = await handle.done;
+  assert.deepEqual(events.at(-1), {
+    type: 'result',
+    ok: false,
+    error: '進捗の同期に失敗',
+  });
+  assert.equal(result.error, '進捗の同期に失敗');
+});
+
+test('runSyncLauncher settles after exit when close never arrives', async () => {
+  const { spawn, children } = makeSpawn();
+  const handle = runSyncLauncher({
+    command: ['subminer'],
+    args: ['sync', 'media-box', '--json'],
+    onEvent: () => {},
+    spawn,
+  });
+  const child = children[0]!;
+  child.stderr.emit('data', Buffer.from('[ERROR] remote refused\n'));
+  // The child is gone, but a descendant still holds the inherited stdio pipes,
+  // so `close` never fires.
+  child.emit('exit', 1, null);
+
+  const result = await handle.done;
+  assert.equal(result.ok, false);
+  assert.match(result.error ?? '', /remote refused/);
+});
+
 test('runSyncLauncher reports failures with the result event error or stderr tail', async () => {
  const { spawn, children } = makeSpawn();
  const handle = runSyncLauncher({
@@ -89,6 +139,52 @@ test('runSyncLauncher falls back to stderr when no result event arrives', async
  assert.match(result.error ?? '', /boom/);
 });

+test('runSyncLauncher settles on exit when the terminal event is already parsed', async () => {
+  const { spawn, children } = makeSpawn();
+  const handle = runSyncLauncher({
+    command: ['subminer'],
+    args: ['sync', 'media-box', '--check', '--json'],
+    onEvent: () => {},
+    spawn,
+  });
+  children[0]!.stdout.emit(
+    'data',
+    Buffer.from('{"type":"result","ok":true,"error":null}\n'),
+  );
+  children[0]!.emit('exit', 0, null);
+
+  const result = await Promise.race([
+    handle.done,
+    new Promise<null>((resolve) => setTimeout(() => resolve(null), 25)),
+  ]);
+  assert.deepEqual(result, { ok: true, error: null });
+});
+
+test('runSyncLauncher waits for terminal NDJSON when exit precedes final stdout data', async () => {
+  const { spawn, children } = makeSpawn();
+  const events: SyncProgressEvent[] = [];
+  const handle = runSyncLauncher({
+    command: ['subminer'],
+    args: ['sync', 'media-box', '--json'],
+    onEvent: (event) => events.push(event),
+    spawn,
+  });
+  const child = children[0]!;
+  let settled = false;
+  void handle.done.then(() => {
+    settled = true;
+  });
+
+  child.emit('exit', 0, null);
+  await Promise.resolve();
+  assert.equal(settled, false);
+
+  child.stdout.emit('data', Buffer.from('{"type":"result","ok":true,"error":null}\n'));
+
+  assert.deepEqual(await handle.done, { ok: true, error: null });
+  assert.deepEqual(events.at(-1), { type: 'result', ok: true, error: null });
+});
+
 test('runSyncLauncher cancel kills the child and resolves as cancelled', async () => {
  const { spawn, children } = makeSpawn();
  const handle = runSyncLauncher({
@@ -97,14 +193,99 @@ test('runSyncLauncher cancel kills the child and resolves as cancelled', async (
    onEvent: () => {},
    spawn,
  });
+  const child = children[0]!;
+  child.kill = () => {
+    child.killed = true;
+    child.emit('exit', null, 'SIGTERM');
+    return true;
+  };
  handle.cancel();
-  assert.equal(children[0]!.killed, true);
+  assert.equal(child.killed, true);

-  const result = await handle.done;
+  const result = await Promise.race([
+    handle.done,
+    new Promise<null>((resolve) => setTimeout(() => resolve(null), 25)),
+  ]);
+  assert.ok(result);
  assert.equal(result.ok, false);
  assert.match(result.error ?? '', /cancel/i);
 });

+test('runSyncLauncher cancel settles a child that already exited without a result', async () => {
+  const { spawn, children } = makeSpawn();
+  const handle = runSyncLauncher({
+    command: ['subminer'],
+    args: ['sync', 'media-box', '--json'],
+    onEvent: () => {},
+    spawn,
+  });
+  const child = children[0]!;
+  // The child is gone, but a descendant still holds the inherited stdio pipes,
+  // so `close` never arrives.
+  child.kill = () => {
+    child.killed = true;
+    return true;
+  };
+  child.emit('exit', null, 'SIGTERM');
+
+  handle.cancel();
+
+  const result = await Promise.race([
+    handle.done,
+    new Promise<null>((resolve) => setTimeout(() => resolve(null), 25)),
+  ]);
+  assert.deepEqual(result, { ok: false, error: 'Sync cancelled.' });
+  assert.equal(child.killed, false);
+});
+
+test('runSyncLauncher times out a child that already exited without a result', async () => {
+  const { spawn, children } = makeSpawn();
+  const handle = runSyncLauncher({
+    command: ['subminer'],
+    args: ['sync', 'media-box', '--check', '--json'],
+    onEvent: () => {},
+    spawn,
+    timeoutMs: 1,
+  });
+  const child = children[0]!;
+  child.kill = () => {
+    child.killed = true;
+    return true;
+  };
+  child.emit('exit', null, 'SIGTERM');
+
+  const result = await Promise.race([
+    handle.done,
+    new Promise<null>((resolve) => setTimeout(() => resolve(null), 25)),
+  ]);
+  assert.deepEqual(result, { ok: false, error: 'Sync operation timed out.' });
+  assert.equal(child.killed, false);
+});
+
+test('runSyncLauncher times out a child that never completes', async () => {
+  const { spawn, children } = makeSpawn();
+  const handle = runSyncLauncher({
+    command: ['subminer'],
+    args: ['sync', 'media-box', '--check', '--json'],
+    onEvent: () => {},
+    spawn,
+    timeoutMs: 1,
+  });
+  const child = children[0]!;
+  child.kill = () => {
+    child.killed = true;
+    child.emit('exit', null, 'SIGTERM');
+    return true;
+  };
+
+  const result = await Promise.race([
+    handle.done,
+    new Promise<null>((resolve) => setTimeout(() => resolve(null), 25)),
+  ]);
+  assert.equal(child.killed, true);
+  assert.deepEqual(result, { ok: false, error: 'Sync operation timed out.' });
+});
+
 test('runSyncLauncher surfaces spawn errors', async () => {
  const { spawn, children } = makeSpawn();
  const handle = runSyncLauncher({
@@ -126,12 +307,24 @@ test('resolveSyncLauncherCommand self-spawns the app in --sync-cli mode', async
    execPath: '/opt/SubMiner/subminer-app',
    appPath: null,
  });
-  assert.deepEqual(packaged.command, ['/opt/SubMiner/subminer-app', '--sync-cli']);
-  assert.equal(packaged.error, null);
+  assert.deepEqual(packaged, ['/opt/SubMiner/subminer-app', '--sync-cli']);

  const dev = resolveSyncLauncherCommand({
    execPath: '/usr/bin/electron',
    appPath: '/home/u/SubMiner',
  });
-  assert.deepEqual(dev.command, ['/usr/bin/electron', '/home/u/SubMiner', '--sync-cli']);
+  assert.deepEqual(dev, ['/usr/bin/electron', '/home/u/SubMiner', '--sync-cli']);
+});
+
+test('sanitizeSyncLauncherEnv removes transported parent startup arguments', () => {
+  const parentEnv = {
+    PATH: '/usr/bin',
+    ELECTRON_RUN_AS_NODE: '1',
+    SUBMINER_APP_ARGC: '2',
+    SUBMINER_APP_ARG_0: '--start',
+    SUBMINER_APP_ARG_1: '--background',
+  };
+
+  assert.deepEqual(sanitizeSyncLauncherEnv(parentEnv), { PATH: '/usr/bin' });
+  assert.equal(parentEnv.SUBMINER_APP_ARGC, '2');
 });
@@ -1,14 +1,22 @@
 import { spawn as nodeSpawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
 import { parseSyncProgressLine, type SyncProgressEvent } from '../../shared/sync/sync-events';
 import { SYNC_CLI_FLAG } from '../../core/services/stats-sync/cli-args';

 /** How long a cancelled sync child gets to exit on SIGTERM before SIGKILL. */
 const CANCEL_GRACE_MS = 5000;

+/**
+ * How long a child that exited without terminal NDJSON gets to flush its
+ * remaining stdout before the exit is treated as authoritative.
+ */
+const EXIT_DRAIN_MS = 2000;
+
 export interface SyncLauncherChildLike {
  stdout: { on(event: 'data', listener: (chunk: Buffer | string) => void): unknown } | null;
  stderr: { on(event: 'data', listener: (chunk: Buffer | string) => void): unknown } | null;
  on(event: 'close', listener: (code: number | null, signal: string | null) => void): unknown;
+  on(event: 'exit', listener: (code: number | null, signal: string | null) => void): unknown;
  on(event: 'error', listener: (error: Error) => void): unknown;
  kill(signal?: NodeJS.Signals): boolean;
 }
@@ -25,9 +33,14 @@ export interface SyncLauncherRunHandle {
  done: Promise<SyncLauncherRunResult>;
 }

-export interface SyncLauncherResolution {
-  command: string[] | null;
-  error: string | null;
+export function sanitizeSyncLauncherEnv(baseEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env = { ...baseEnv };
+  delete env.ELECTRON_RUN_AS_NODE;
+  delete env.SUBMINER_APP_ARGC;
+  for (const name of Object.keys(env)) {
+    if (name.startsWith('SUBMINER_APP_ARG_')) delete env[name];
+  }
+  return env;
 }

 // Sync runs in a child copy of this app in headless --sync-cli mode: same
@@ -39,13 +52,10 @@ export function resolveSyncLauncherCommand(
    execPath?: string;
    appPath?: string | null;
  } = {},
-): SyncLauncherResolution {
+): string[] {
  const execPath = deps.execPath ?? process.execPath;
  const appPath = deps.appPath ?? null;
-  return {
-    command: appPath ? [execPath, appPath, SYNC_CLI_FLAG] : [execPath, SYNC_CLI_FLAG],
-    error: null,
-  };
+  return appPath ? [execPath, appPath, SYNC_CLI_FLAG] : [execPath, SYNC_CLI_FLAG];
 }

 export function runSyncLauncher(options: {
@@ -54,14 +64,14 @@ export function runSyncLauncher(options: {
  onEvent: (event: SyncProgressEvent) => void;
  onStderr?: (text: string) => void;
  spawn?: SyncLauncherSpawn;
+  timeoutMs?: number;
 }): SyncLauncherRunHandle {
  const spawn =
    options.spawn ??
    ((command, args) => {
      // The child must boot as a full Electron app (its entry handles
      // --sync-cli); a leaked ELECTRON_RUN_AS_NODE would turn it into node.
-      const env = { ...process.env };
-      delete env.ELECTRON_RUN_AS_NODE;
+      const env = sanitizeSyncLauncherEnv(process.env);
      return nodeSpawn(command, args, { stdio: 'pipe', env });
    });
  const [executable, ...prefixArgs] = options.command;
@@ -70,41 +80,69 @@ export function runSyncLauncher(options: {
  let stdoutBuffer = '';
  let stderrTail = '';
  let resultEvent: Extract<SyncProgressEvent, { type: 'result' }> | null = null;
-  let cancelled = false;
+  let terminationError: string | null = null;
+  let settleAfterTerminalEvent: (() => void) | null = null;
+  let settleAfterTermination: (() => boolean) | null = null;
+
+  // Decode incrementally: a multibyte character can straddle a chunk boundary,
+  // and a per-chunk toString() would corrupt it (sync payloads carry Japanese
+  // media titles and error detail).
+  const stdoutDecoder = new StringDecoder('utf8');
+  const stderrDecoder = new StringDecoder('utf8');
+  const decodeChunk = (decoder: StringDecoder, chunk: Buffer | string): string =>
+    typeof chunk === 'string' ? chunk : decoder.write(chunk);

  child.stdout?.on('data', (chunk) => {
-    stdoutBuffer += chunk.toString();
+    stdoutBuffer += decodeChunk(stdoutDecoder, chunk);
    let newlineIndex = stdoutBuffer.indexOf('\n');
    while (newlineIndex !== -1) {
      const line = stdoutBuffer.slice(0, newlineIndex);
      stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
      const event = parseSyncProgressLine(line);
      if (event) {
-        if (event.type === 'result') resultEvent = event;
+        if (event.type === 'result') {
+          resultEvent = event;
+          settleAfterTerminalEvent?.();
+        }
        options.onEvent(event);
      }
      newlineIndex = stdoutBuffer.indexOf('\n');
    }
  });
  child.stderr?.on('data', (chunk) => {
-    const text = chunk.toString();
+    const text = decodeChunk(stderrDecoder, chunk);
    stderrTail = `${stderrTail}${text}`.slice(-4000);
    options.onStderr?.(text);
  });

+  let killTimer: ReturnType<typeof setTimeout> | null = null;
+  let operationTimer: ReturnType<typeof setTimeout> | null = null;
+  let drainTimer: ReturnType<typeof setTimeout> | null = null;
+  const clearTimers = (): void => {
+    if (killTimer !== null) clearTimeout(killTimer);
+    if (operationTimer !== null) clearTimeout(operationTimer);
+    if (drainTimer !== null) clearTimeout(drainTimer);
+    killTimer = null;
+    operationTimer = null;
+    drainTimer = null;
+  };
+
  const done = new Promise<SyncLauncherRunResult>((resolve) => {
    let settled = false;
+    let exitObserved = false;
+    let exitCode: number | null = null;
    const settle = (result: SyncLauncherRunResult): void => {
      if (settled) return;
      settled = true;
+      clearTimers();
      resolve(result);
    };
    child.on('error', (error) => {
      settle({ ok: false, error: error.message });
    });
-    child.on('close', (code) => {
-      if (cancelled) {
-        settle({ ok: false, error: 'Sync cancelled.' });
+    const settleFromExit = (code: number | null) => {
+      if (terminationError) {
+        settle({ ok: false, error: terminationError });
        return;
      }
      if (code === 0) {
@@ -114,39 +152,70 @@ export function runSyncLauncher(options: {
      const error =
        resultEvent?.error ?? (stderrTail.trim() || `Launcher exited with code ${code ?? 'null'}.`);
      settle({ ok: false, error });
+    };
+    settleAfterTerminalEvent = () => {
+      if (exitObserved) settleFromExit(exitCode);
+    };
+    settleAfterTermination = () => {
+      if (!exitObserved) return false;
+      settleFromExit(exitCode);
+      return true;
+    };
+    // Electron descendants can retain inherited stdio pipes after the main
+    // child exits, delaying `close` indefinitely. Once terminal NDJSON has
+    // arrived, `exit` is authoritative; keep `close` as the fallback.
+    child.on('exit', (code) => {
+      exitObserved = true;
+      exitCode = code;
+      if (resultEvent || terminationError) {
+        settleFromExit(code);
+        return;
+      }
+      // No terminal event yet: stdout may still be flushing, so give it a
+      // bounded window rather than waiting on a `close` that retained pipes
+      // can withhold forever.
+      drainTimer = setTimeout(() => {
+        drainTimer = null;
+        settleFromExit(code);
+      }, EXIT_DRAIN_MS);
+      drainTimer.unref?.();
    });
+    child.on('close', settleFromExit);
  });

-  // A sync child blocked on an ssh password prompt ignores SIGTERM, so escalate
-  // to SIGKILL if it is still alive after a grace period. The timer is cleared
-  // on close so a cancelled run cannot hold the process open.
-  let killTimer: ReturnType<typeof setTimeout> | null = null;
-  const clearKillTimer = (): void => {
-    if (killTimer === null) return;
-    clearTimeout(killTimer);
-    killTimer = null;
-  };
-  child.on('close', clearKillTimer);
-
-  return {
-    cancel: () => {
-      if (cancelled) return;
-      cancelled = true;
+  // A sync child blocked on an ssh password prompt may ignore SIGTERM, so
+  // escalate to SIGKILL after a grace period.
+  const terminate = (error: string): void => {
+    if (terminationError) return;
+    terminationError = error;
+    // A child that already exited without terminal NDJSON is still waiting on
+    // `close`, which descendants holding inherited pipes can delay
+    // indefinitely. There is nothing left to signal, so settle now instead of
+    // leaving `done` (and the quit-time shutdown that awaits it) pending.
+    if (settleAfterTermination?.()) return;
+    killTimer = setTimeout(() => {
+      killTimer = null;
      try {
-        child.kill('SIGTERM');
+        child.kill('SIGKILL');
      } catch {
        // process may already be gone
      }
-      killTimer = setTimeout(() => {
-        killTimer = null;
-        try {
-          child.kill('SIGKILL');
-        } catch {
-          // process may already be gone
-        }
-      }, CANCEL_GRACE_MS);
-      killTimer.unref?.();
-    },
+    }, CANCEL_GRACE_MS);
+    killTimer.unref?.();
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      // process may already be gone
+    }
+  };
+
+  if (options.timeoutMs !== undefined) {
+    operationTimer = setTimeout(() => terminate('Sync operation timed out.'), options.timeoutMs);
+    operationTimer.unref?.();
+  }
+
+  return {
+    cancel: () => terminate('Sync cancelled.'),
    done,
  };
 }
@@ -0,0 +1,23 @@
+import {
+  readSyncHostsState,
+  writeSyncHostsState,
+  type SyncHostsState,
+} from '../../shared/sync/sync-hosts-store';
+
+interface SyncUiHostsStateDeps {
+  hostsFilePath: string;
+  broadcastStateChanged: () => void;
+}
+
+export function createSyncUiHostsState(deps: SyncUiHostsStateDeps) {
+  function readState(): SyncHostsState {
+    return readSyncHostsState(deps.hostsFilePath);
+  }
+
+  function writeState(state: SyncHostsState): void {
+    writeSyncHostsState(deps.hostsFilePath, state);
+    deps.broadcastStateChanged();
+  }
+
+  return { readState, writeState };
+}
@@ -0,0 +1,63 @@
+import { IPC_CHANNELS } from '../../shared/ipc/contracts';
+import { removeSyncHost, upsertSyncHost } from '../../shared/sync/sync-hosts-store';
+import type {
+  SyncUiHostUpdateRequest,
+  SyncUiRunRequest,
+  SyncUiSnapshot,
+  SyncUiStartResult,
+} from '../../types/sync-ui';
+
+interface SyncUiIpcHandlersDeps {
+  ipcMain: {
+    handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): unknown;
+  };
+  nowMs: () => number;
+  revealPath: (targetPath: string) => void;
+  pickSnapshotFile: () => Promise<string | null>;
+  getSnapshot: () => SyncUiSnapshot;
+  readState: () => SyncUiSnapshot['hosts'];
+  writeState: (state: SyncUiSnapshot['hosts']) => void;
+  runHostSync: (request: SyncUiRunRequest) => SyncUiStartResult;
+  cancelRun: () => boolean;
+  checkHost: (host: string) => unknown;
+  createSnapshot: () => SyncUiStartResult;
+  mergeSnapshotFile: (filePath: string, force?: boolean) => SyncUiStartResult;
+  deleteSnapshot: (filePath: string) => void;
+}
+
+export function registerSyncUiIpcHandlers(deps: SyncUiIpcHandlersDeps): void {
+  const channels = IPC_CHANNELS.request;
+  deps.ipcMain.handle(channels.syncUiGetSnapshot, () => deps.getSnapshot());
+  deps.ipcMain.handle(channels.syncUiSaveHost, (_event, update) => {
+    deps.writeState(
+      upsertSyncHost(deps.readState(), update as SyncUiHostUpdateRequest, deps.nowMs()),
+    );
+  });
+  deps.ipcMain.handle(channels.syncUiRemoveHost, (_event, host) => {
+    deps.writeState(removeSyncHost(deps.readState(), String(host)));
+  });
+  deps.ipcMain.handle(channels.syncUiSetAutoSyncInterval, (_event, minutes) => {
+    const value = Number(minutes);
+    if (!Number.isFinite(value) || value < 1 || value > 24 * 60) {
+      throw new Error('Auto-sync interval must be between 1 and 1440 minutes.');
+    }
+    deps.writeState({ ...deps.readState(), autoSyncIntervalMinutes: Math.floor(value) });
+  });
+  deps.ipcMain.handle(channels.syncUiRunSync, (_event, request) =>
+    deps.runHostSync(request as SyncUiRunRequest),
+  );
+  deps.ipcMain.handle(channels.syncUiCancelRun, () => deps.cancelRun());
+  deps.ipcMain.handle(channels.syncUiCheckHost, (_event, host) => deps.checkHost(String(host)));
+  deps.ipcMain.handle(channels.syncUiCreateSnapshot, () => deps.createSnapshot());
+  deps.ipcMain.handle(channels.syncUiMergeSnapshotFile, (_event, filePath, force) =>
+    deps.mergeSnapshotFile(String(filePath), force === true),
+  );
+  deps.ipcMain.handle(channels.syncUiDeleteSnapshot, (_event, filePath) => {
+    deps.deleteSnapshot(String(filePath));
+  });
+  deps.ipcMain.handle(channels.syncUiRevealSnapshot, (_event, filePath) => {
+    deps.revealPath(String(filePath));
+    return true;
+  });
+  deps.ipcMain.handle(channels.syncUiPickSnapshotFile, () => deps.pickSnapshotFile());
+}
@@ -0,0 +1,183 @@
+import { IPC_CHANNELS } from '../../shared/ipc/contracts';
+import { isValidSyncHost } from '../../shared/sync/sync-hosts-store';
+import type { SyncProgressEvent } from '../../shared/sync/sync-events';
+import type {
+  SyncUiCheckResult,
+  SyncUiRunKind,
+  SyncUiRunState,
+  SyncUiStartResult,
+} from '../../types/sync-ui';
+import {
+  runSyncLauncher,
+  type SyncLauncherRunHandle,
+  type SyncLauncherRunResult,
+} from './sync-launcher-client';
+
+interface ActiveRun {
+  id: number;
+  kind: SyncUiRunKind;
+  host: string | null;
+  handle: SyncLauncherRunHandle;
+  resultSeen: boolean;
+  completion?: Promise<void>;
+}
+
+interface SyncUiRunLifecycleDeps {
+  runLauncher: typeof runSyncLauncher;
+  resolveLauncherCommand: () => string[];
+  log?: (message: string) => void;
+  notify?: (payload: { title: string; body: string; variant: 'success' | 'error' }) => void;
+  sendToWindow: (channel: string, payload?: unknown) => void;
+  broadcastStateChanged: () => void;
+}
+
+export function createSyncUiRunLifecycle(deps: SyncUiRunLifecycleDeps) {
+  let runCounter = 0;
+  let currentRun: ActiveRun | null = null;
+
+  function launchRun(
+    kind: SyncUiRunKind,
+    host: string | null,
+    args: string[],
+    options: {
+      notify?: boolean;
+      timeoutMs?: number;
+      emitProgress?: boolean;
+      onEvent?: (event: SyncProgressEvent) => void;
+    } = {},
+  ): { start: SyncUiStartResult; done: Promise<SyncLauncherRunResult> | null } {
+    if (currentRun) {
+      return {
+        start: { started: false, runId: null, reason: 'A sync operation is already running.' },
+        done: null,
+      };
+    }
+    const emitProgress = options.emitProgress ?? true;
+    runCounter += 1;
+    const runId = runCounter;
+    const run: ActiveRun = {
+      id: runId,
+      kind,
+      host,
+      resultSeen: false,
+      handle: deps.runLauncher({
+        command: deps.resolveLauncherCommand(),
+        args,
+        timeoutMs: options.timeoutMs,
+        onEvent: (event: SyncProgressEvent) => {
+          if (event.type === 'result') run.resultSeen = true;
+          options.onEvent?.(event);
+          if (emitProgress) {
+            deps.sendToWindow(IPC_CHANNELS.event.syncUiProgress, { runId, kind, host, event });
+          }
+        },
+        onStderr: (text) => deps.log?.(`[sync-ui] ${text.trimEnd()}`),
+      }),
+    };
+    currentRun = run;
+    run.completion = run.handle.done
+      .then((result: SyncLauncherRunResult) => {
+        if (currentRun?.id === runId) currentRun = null;
+        if (emitProgress && !run.resultSeen) {
+          deps.sendToWindow(IPC_CHANNELS.event.syncUiProgress, {
+            runId,
+            kind,
+            host,
+            event: { type: 'result', ok: result.ok, error: result.error },
+          });
+        }
+        deps.broadcastStateChanged();
+        if (options.notify && deps.notify) {
+          const target = host ?? 'local database';
+          deps.notify(
+            result.ok
+              ? { title: 'Sync complete', body: `Synced with ${target}`, variant: 'success' }
+              : {
+                  title: 'Sync failed',
+                  body: `${target}: ${result.error ?? 'unknown error'}`,
+                  variant: 'error',
+                },
+          );
+        }
+      })
+      .catch((error) => {
+        deps.log?.(
+          `[sync-ui] Post-run cleanup failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      });
+    return { start: { started: true, runId, reason: null }, done: run.handle.done };
+  }
+
+  function startRun(
+    kind: SyncUiRunKind,
+    host: string | null,
+    args: string[],
+    options: { notify?: boolean } = {},
+  ): SyncUiStartResult {
+    return launchRun(kind, host, args, options).start;
+  }
+
+  function checkHost(host: string): Promise<SyncUiCheckResult> {
+    const trimmed = host.trim();
+    const failed = (error: string): SyncUiCheckResult => ({
+      host: trimmed,
+      sshOk: false,
+      remoteCommand: null,
+      remoteVersion: null,
+      ok: false,
+      error,
+    });
+    if (!isValidSyncHost(trimmed)) {
+      return Promise.resolve(failed(`Invalid sync host: ${host}`));
+    }
+    let checkResult: SyncUiCheckResult | null = null;
+    const { start, done } = launchRun('check', trimmed, ['sync', trimmed, '--check', '--json'], {
+      timeoutMs: 30_000,
+      emitProgress: false,
+      onEvent: (event) => {
+        if (event.type === 'check-result') {
+          checkResult = {
+            host: event.host,
+            sshOk: event.sshOk,
+            remoteCommand: event.remoteCommand,
+            remoteVersion: event.remoteVersion,
+            ok: event.ok,
+            error: event.error,
+          };
+        }
+      },
+    });
+    if (!start.started || !done) {
+      return Promise.resolve(failed(start.reason ?? 'A sync operation is already running.'));
+    }
+    return done.then((result) => checkResult ?? failed(result.error ?? 'Connection check failed.'));
+  }
+
+  function cancelRun(): boolean {
+    if (!currentRun) return false;
+    currentRun.handle.cancel();
+    return true;
+  }
+
+  async function shutdown(): Promise<void> {
+    const run = currentRun;
+    if (!run) return;
+    run.handle.cancel();
+    await (run.completion ?? run.handle.done.then(() => undefined));
+  }
+
+  function runState(): SyncUiRunState {
+    return currentRun
+      ? { running: true, runId: currentRun.id, kind: currentRun.kind, host: currentRun.host }
+      : { running: false, runId: null, kind: null, host: null };
+  }
+
+  return {
+    startRun,
+    checkHost,
+    cancelRun,
+    shutdown,
+    runState,
+    isRunning: () => currentRun !== null,
+  };
+}
@@ -9,6 +9,7 @@ import { createSyncUiRuntime, type SyncUiRuntimeDeps } from './sync-ui-runtime';

 interface LauncherCall {
  args: string[];
+  timeoutMs: number | undefined;
  onEvent: (event: SyncProgressEvent) => void;
  finish: (result: { ok: boolean; error: string | null }) => void;
  cancelled: boolean;
@@ -34,7 +35,7 @@ function makeTestRig(root: string, overrides: Partial<SyncUiRuntimeDeps> = {}) {
    hostsFilePath: path.join(root, 'sync-hosts.json'),
    snapshotsDir: path.join(root, 'snapshots'),
    getDbPath: () => path.join(root, 'immersion.sqlite'),
-    resolveLauncherCommand: () => ({ command: ['subminer'], error: null }),
+    resolveLauncherCommand: () => ['subminer'],
    runLauncher: (options): SyncLauncherRunHandle => {
      let finish: (result: { ok: boolean; error: string | null }) => void = () => {};
      const done = new Promise<{ ok: boolean; error: string | null }>((resolve) => {
@@ -42,6 +43,7 @@ function makeTestRig(root: string, overrides: Partial<SyncUiRuntimeDeps> = {}) {
      });
      const call: LauncherCall = {
        args: options.args,
+        timeoutMs: options.timeoutMs,
        onEvent: options.onEvent,
        finish,
        cancelled: false,
@@ -104,21 +106,24 @@ test('registerHandlers registers every sync-ui request channel', () =>

 test('save/remove host round-trips through the hosts file', () =>
  withTempDir(async (root) => {
-    const { invoke } = makeTestRig(root);
-    const saved = (await invoke('sync-ui:save-host', {
+    const { invoke, sent } = makeTestRig(root);
+    await invoke('sync-ui:save-host', {
      host: 'user@laptop',
      label: 'Laptop',
      direction: 'pull',
      autoSync: true,
-    })) as { hosts: Array<{ host: string; direction: string; autoSync: boolean }> };
-    assert.equal(saved.hosts.length, 1);
-    assert.equal(saved.hosts[0]!.direction, 'pull');
-    assert.equal(saved.hosts[0]!.autoSync, true);
-
-    const removed = (await invoke('sync-ui:remove-host', 'user@laptop')) as {
-      hosts: unknown[];
+    });
+    assert.ok(sent.some((entry) => entry.channel === 'sync-ui:state-changed'));
+    const saved = (await invoke('sync-ui:get-snapshot')) as {
+      hosts: { hosts: Array<{ host: string; direction: string; autoSync: boolean }> };
    };
-    assert.equal(removed.hosts.length, 0);
+    assert.equal(saved.hosts.hosts.length, 1);
+    assert.equal(saved.hosts.hosts[0]!.direction, 'pull');
+    assert.equal(saved.hosts.hosts[0]!.autoSync, true);
+
+    await invoke('sync-ui:remove-host', 'user@laptop');
+    const removed = (await invoke('sync-ui:get-snapshot')) as { hosts: { hosts: unknown[] } };
+    assert.equal(removed.hosts.hosts.length, 0);
  }));

 test('save-host rejects invalid hosts', () =>
@@ -130,13 +135,12 @@ test('save-host rejects invalid hosts', () =>
    );
  }));

-test('run-sync spawns the launcher, forwards progress, and rejects concurrent runs', () =>
+test('run-sync uses live mode, forwards progress, and rejects concurrent runs', () =>
  withTempDir(async (root) => {
    const { invoke, launcherCalls, sent } = makeTestRig(root);
    const start = (await invoke('sync-ui:run-sync', {
      host: 'media-box',
      direction: 'push',
-      force: true,
    })) as { started: boolean; runId: number };
    assert.equal(start.started, true);
    assert.deepEqual(launcherCalls[0]!.args, ['sync', 'media-box', '--push', '--force', '--json']);
@@ -193,7 +197,7 @@ test('create-snapshot runs the launcher with a timestamped path under the snapsh

 test('delete-snapshot refuses paths outside the snapshots dir', () =>
  withTempDir(async (root) => {
-    const { invoke } = makeTestRig(root);
+    const { invoke, sent } = makeTestRig(root);
    fs.mkdirSync(path.join(root, 'snapshots'), { recursive: true });
    const inside = path.join(root, 'snapshots', 'immersion-1.sqlite');
    fs.writeFileSync(inside, 'x');
@@ -201,10 +205,13 @@ test('delete-snapshot refuses paths outside the snapshots dir', () =>
    fs.writeFileSync(outside, 'x');

    await assert.rejects(async () => invoke('sync-ui:delete-snapshot', outside));
-    const remaining = (await invoke('sync-ui:delete-snapshot', inside)) as unknown[];
-    assert.equal(remaining.length, 0);
+    await invoke('sync-ui:delete-snapshot', inside);
    assert.equal(fs.existsSync(inside), false);
    assert.equal(fs.existsSync(outside), true);
+    // The renderer relies on the state-changed broadcast to refresh its list.
+    assert.ok(sent.some((entry) => entry.channel === 'sync-ui:state-changed'));
+    const snapshot = (await invoke('sync-ui:get-snapshot')) as { snapshots: unknown[] };
+    assert.equal(snapshot.snapshots.length, 0);
  }));

 test('check-host resolves with the check-result event', () =>
@@ -216,6 +223,7 @@ test('check-host resolves with the check-result event', () =>
    }>;
    await new Promise((resolve) => setImmediate(resolve));
    assert.deepEqual(launcherCalls[0]!.args, ['sync', 'media-box', '--check', '--json']);
+    assert.equal(launcherCalls[0]!.timeoutMs, 30_000);
    launcherCalls[0]!.onEvent({
      type: 'check-result',
      host: 'media-box',
@@ -1,34 +1,17 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import { IPC_CHANNELS } from '../../shared/ipc/contracts';
 import {
  isValidSyncHost,
-  readSyncHostsState,
-  removeSyncHost,
  upsertSyncHost,
-  writeSyncHostsState,
  type SyncDirection,
-  type SyncHostsState,
 } from '../../shared/sync/sync-hosts-store';
-import type { SyncProgressEvent } from '../../shared/sync/sync-events';
-import type {
-  SyncUiCheckResult,
-  SyncUiHostUpdateRequest,
-  SyncUiRunKind,
-  SyncUiRunRequest,
-  SyncUiRunState,
-  SyncUiSnapshot,
-  SyncUiSnapshotFile,
-  SyncUiStartResult,
-} from '../../types/sync-ui';
-import type {
-  SyncLauncherResolution,
-  SyncLauncherRunHandle,
-  SyncLauncherRunResult,
-} from './sync-launcher-client';
+import type { SyncUiRunRequest, SyncUiSnapshot } from '../../types/sync-ui';
+import { createSyncUiHostsState } from './sync-ui-hosts-state';
+import { registerSyncUiIpcHandlers } from './sync-ui-ipc-handlers';
+import { createSyncUiRunLifecycle } from './sync-ui-run-lifecycle';
 import { runSyncLauncher } from './sync-launcher-client';
+import { createSyncUiSnapshots } from './sync-ui-snapshots';

-export interface SyncUiWindowLike {
+interface SyncUiWindowLike {
  isDestroyed(): boolean;
  webContents: { send(channel: string, payload?: unknown): void };
 }
@@ -40,7 +23,7 @@ export interface SyncUiRuntimeDeps {
  hostsFilePath: string;
  snapshotsDir: string;
  getDbPath: () => string;
-  resolveLauncherCommand: () => SyncLauncherResolution;
+  resolveLauncherCommand: () => string[];
  runLauncher: typeof runSyncLauncher;
  getWindow: () => SyncUiWindowLike | null;
  pickSnapshotFile: () => Promise<string | null>;
@@ -50,27 +33,7 @@ export interface SyncUiRuntimeDeps {
  notify?: (payload: { title: string; body: string; variant: 'success' | 'error' }) => void;
 }

-interface ActiveRun {
-  id: number;
-  kind: SyncUiRunKind;
-  host: string | null;
-  handle: SyncLauncherRunHandle;
-  resultSeen: boolean;
-  completion?: Promise<void>;
-}
-
-// Milliseconds are part of the stamp so two snapshots taken in the same second
-// do not land on the same path and silently overwrite each other.
-export function formatSnapshotName(nowMs: number): string {
-  const iso = new Date(nowMs).toISOString();
-  const stamp = iso.slice(0, 23).replace(/[-:.]/g, '').replace('T', '-');
-  return `immersion-${stamp}.sqlite`;
-}
-
 export function createSyncUiRuntime(deps: SyncUiRuntimeDeps) {
-  let runCounter = 0;
-  let currentRun: ActiveRun | null = null;
-
  function sendToWindow(channel: string, payload?: unknown): void {
    const window = deps.getWindow();
    if (!window || window.isDestroyed()) return;
@@ -81,130 +44,35 @@ export function createSyncUiRuntime(deps: SyncUiRuntimeDeps) {
    sendToWindow(IPC_CHANNELS.event.syncUiStateChanged);
  }

-  function readState(): SyncHostsState {
-    return readSyncHostsState(deps.hostsFilePath);
-  }
-
-  function writeState(state: SyncHostsState): SyncHostsState {
-    writeSyncHostsState(deps.hostsFilePath, state);
-    broadcastStateChanged();
-    return state;
-  }
-
-  function listSnapshots(): SyncUiSnapshotFile[] {
-    let names: string[];
-    try {
-      names = fs.readdirSync(deps.snapshotsDir);
-    } catch {
-      return [];
-    }
-    const files: SyncUiSnapshotFile[] = [];
-    for (const name of names) {
-      if (!name.endsWith('.sqlite')) continue;
-      const filePath = path.join(deps.snapshotsDir, name);
-      try {
-        const stat = fs.statSync(filePath);
-        if (!stat.isFile()) continue;
-        files.push({
-          path: filePath,
-          name,
-          sizeBytes: stat.size,
-          modifiedAtMs: stat.mtimeMs,
-        });
-      } catch {
-        // file disappeared between readdir and stat
-      }
-    }
-    files.sort((a, b) => b.modifiedAtMs - a.modifiedAtMs);
-    return files;
-  }
-
-  function runState(): SyncUiRunState {
-    return currentRun
-      ? { running: true, runId: currentRun.id, kind: currentRun.kind, host: currentRun.host }
-      : { running: false, runId: null, kind: null, host: null };
-  }
+  const hostsState = createSyncUiHostsState({
+    hostsFilePath: deps.hostsFilePath,
+    broadcastStateChanged,
+  });
+  const runLifecycle = createSyncUiRunLifecycle({
+    runLauncher: deps.runLauncher,
+    resolveLauncherCommand: deps.resolveLauncherCommand,
+    log: deps.log,
+    notify: deps.notify,
+    sendToWindow,
+    broadcastStateChanged,
+  });
+  const snapshots = createSyncUiSnapshots({
+    snapshotsDir: deps.snapshotsDir,
+    nowMs: deps.nowMs,
+    startRun: runLifecycle.startRun,
+    broadcastStateChanged,
+  });

  function getSnapshot(): SyncUiSnapshot {
    return {
      dbPath: deps.getDbPath(),
-      hosts: readState(),
+      hosts: hostsState.readState(),
      snapshotsDir: deps.snapshotsDir,
-      snapshots: listSnapshots(),
-      run: runState(),
+      snapshots: snapshots.listSnapshots(),
+      run: runLifecycle.runState(),
    };
  }

-  function startRun(
-    kind: SyncUiRunKind,
-    host: string | null,
-    args: string[],
-    options: { notify?: boolean } = {},
-  ): SyncUiStartResult {
-    if (currentRun) {
-      return {
-        started: false,
-        runId: null,
-        reason: 'A sync operation is already running.',
-      };
-    }
-    const resolution = deps.resolveLauncherCommand();
-    if (!resolution.command) {
-      return { started: false, runId: null, reason: resolution.error };
-    }
-    runCounter += 1;
-    const runId = runCounter;
-    const run: ActiveRun = {
-      id: runId,
-      kind,
-      host,
-      resultSeen: false,
-      handle: deps.runLauncher({
-        command: resolution.command,
-        args,
-        onEvent: (event: SyncProgressEvent) => {
-          if (event.type === 'result') run.resultSeen = true;
-          sendToWindow(IPC_CHANNELS.event.syncUiProgress, { runId, kind, host, event });
-        },
-        onStderr: (text) => deps.log?.(`[sync-ui] ${text.trimEnd()}`),
-      }),
-    };
-    currentRun = run;
-    run.completion = run.handle.done
-      .then((result: SyncLauncherRunResult) => {
-        if (currentRun?.id === runId) currentRun = null;
-        // If the launcher died without emitting a result event (spawn failure,
-        // kill), synthesize one so the renderer can settle its progress view.
-        if (!run.resultSeen) {
-          sendToWindow(IPC_CHANNELS.event.syncUiProgress, {
-            runId,
-            kind,
-            host,
-            event: { type: 'result', ok: result.ok, error: result.error },
-          });
-        }
-        broadcastStateChanged();
-        if (options.notify && deps.notify) {
-          const target = host ?? 'local database';
-          deps.notify(
-            result.ok
-              ? { title: 'Sync complete', body: `Synced with ${target}`, variant: 'success' }
-              : {
-                  title: 'Sync failed',
-                  body: `${target}: ${result.error ?? 'unknown error'}`,
-                  variant: 'error',
-                },
-          );
-        }
-      })
-      .catch((error) => {
-        deps.log?.(
-          `[sync-ui] Post-run cleanup failed: ${error instanceof Error ? error.message : String(error)}`,
-        );
-      });
-    return { started: true, runId, reason: null };
-  }
-
  function runHostSync(request: SyncUiRunRequest, options: { notify?: boolean } = {}) {
    const host = request.host.trim();
    if (!isValidSyncHost(host)) {
@@ -214,164 +82,51 @@ export function createSyncUiRuntime(deps: SyncUiRuntimeDeps) {
    const args = ['sync', host];
    if (direction === 'push') args.push('--push');
    if (direction === 'pull') args.push('--pull');
-    if (request.force) args.push('--force');
-    args.push('--json');
-    const result = startRun('host-sync', host, args, options);
+    // The sync window runs inside the resident app, so waiting for all app
+    // writers to disappear would make manual and automatic sync impossible.
+    // WAL keeps snapshots consistent, transactional merges serialize with live
+    // writes, and unfinished sessions wait for a later sync after finalization.
+    args.push('--force', '--json');
+    const result = runLifecycle.startRun('host-sync', host, args, options);
    if (result.started) {
-      // Remember the host (and the direction used) before the launcher's own
-      // bookkeeping lands, so it shows up in the UI immediately.
-      writeState(upsertSyncHost(readState(), { host, direction: request.direction }, deps.nowMs()));
+      // Persist before launcher bookkeeping lands so the host appears immediately.
+      hostsState.writeState(
+        upsertSyncHost(
+          hostsState.readState(),
+          { host, direction: request.direction },
+          deps.nowMs(),
+        ),
+      );
    }
    return result;
  }

-  function checkHost(host: string): Promise<SyncUiCheckResult> {
-    const trimmed = host.trim();
-    const failed = (error: string): SyncUiCheckResult => ({
-      host: trimmed,
-      sshOk: false,
-      remoteCommand: null,
-      remoteVersion: null,
-      ok: false,
-      error,
-    });
-    if (!isValidSyncHost(trimmed)) {
-      return Promise.resolve(failed(`Invalid sync host: ${host}`));
-    }
-    if (currentRun) {
-      return Promise.resolve(failed('A sync operation is already running.'));
-    }
-    const resolution = deps.resolveLauncherCommand();
-    if (!resolution.command) {
-      return Promise.resolve(failed(resolution.error ?? 'Launcher unavailable.'));
-    }
-    return new Promise((resolve) => {
-      let checkResult: SyncUiCheckResult | null = null;
-      runCounter += 1;
-      const runId = runCounter;
-      const handle = deps.runLauncher({
-        command: resolution.command!,
-        args: ['sync', trimmed, '--check', '--json'],
-        onEvent: (event) => {
-          if (event.type === 'check-result') {
-            checkResult = {
-              host: event.host,
-              sshOk: event.sshOk,
-              remoteCommand: event.remoteCommand,
-              remoteVersion: event.remoteVersion,
-              ok: event.ok,
-              error: event.error,
-            };
-          }
-        },
-        onStderr: (text) => deps.log?.(`[sync-ui check] ${text.trimEnd()}`),
-      });
-      const run: ActiveRun = {
-        id: runId,
-        kind: 'check',
-        host: trimmed,
-        handle,
-        resultSeen: false,
-      };
-      currentRun = run;
-      run.completion = handle.done
-        .then((result) => {
-          if (currentRun?.id === runId) currentRun = null;
-          resolve(checkResult ?? failed(result.error ?? 'Connection check failed.'));
-          broadcastStateChanged();
-        })
-        .catch((error) => {
-          if (currentRun?.id === runId) currentRun = null;
-          resolve(failed(error instanceof Error ? error.message : String(error)));
-          deps.log?.(
-            `[sync-ui check] Cleanup failed: ${error instanceof Error ? error.message : String(error)}`,
-          );
-        });
-    });
-  }
-
-  function createSnapshot(): SyncUiStartResult {
-    const outPath = path.join(deps.snapshotsDir, formatSnapshotName(deps.nowMs()));
-    return startRun('snapshot', null, ['sync', '--snapshot', outPath, '--json']);
-  }
-
-  function mergeSnapshotFile(filePath: string, force = false): SyncUiStartResult {
-    if (!fs.existsSync(filePath)) {
-      return { started: false, runId: null, reason: `Snapshot file not found: ${filePath}` };
-    }
-    const args = ['sync', '--merge', filePath];
-    if (force) args.push('--force');
-    args.push('--json');
-    return startRun('merge', null, args);
-  }
-
-  function deleteSnapshot(filePath: string): SyncUiSnapshotFile[] {
-    const resolved = path.resolve(filePath);
-    const dir = path.resolve(deps.snapshotsDir);
-    if (resolved !== path.join(dir, path.basename(resolved)) || !resolved.endsWith('.sqlite')) {
-      throw new Error('Refusing to delete a file outside the snapshots directory.');
-    }
-    fs.rmSync(resolved, { force: true });
-    broadcastStateChanged();
-    return listSnapshots();
-  }
-
-  function cancelRun(): boolean {
-    if (!currentRun) return false;
-    currentRun.handle.cancel();
-    return true;
-  }
-
-  async function shutdown(): Promise<void> {
-    const run = currentRun;
-    if (!run) return;
-    run.handle.cancel();
-    await (run.completion ?? run.handle.done.then(() => undefined));
-  }
-
  function registerHandlers(): void {
-    const channels = IPC_CHANNELS.request;
-    deps.ipcMain.handle(channels.syncUiGetSnapshot, () => getSnapshot());
-    deps.ipcMain.handle(channels.syncUiSaveHost, (_event, update) =>
-      writeState(upsertSyncHost(readState(), update as SyncUiHostUpdateRequest, deps.nowMs())),
-    );
-    deps.ipcMain.handle(channels.syncUiRemoveHost, (_event, host) =>
-      writeState(removeSyncHost(readState(), String(host))),
-    );
-    deps.ipcMain.handle(channels.syncUiSetAutoSyncInterval, (_event, minutes) => {
-      const value = Number(minutes);
-      if (!Number.isFinite(value) || value < 1 || value > 24 * 60) {
-        throw new Error('Auto-sync interval must be between 1 and 1440 minutes.');
-      }
-      return writeState({ ...readState(), autoSyncIntervalMinutes: Math.floor(value) });
+    registerSyncUiIpcHandlers({
+      ipcMain: deps.ipcMain,
+      nowMs: deps.nowMs,
+      revealPath: deps.revealPath,
+      pickSnapshotFile: deps.pickSnapshotFile,
+      getSnapshot,
+      readState: hostsState.readState,
+      writeState: hostsState.writeState,
+      runHostSync,
+      cancelRun: runLifecycle.cancelRun,
+      checkHost: runLifecycle.checkHost,
+      createSnapshot: snapshots.createSnapshot,
+      mergeSnapshotFile: snapshots.mergeSnapshotFile,
+      deleteSnapshot: snapshots.deleteSnapshot,
    });
-    deps.ipcMain.handle(channels.syncUiRunSync, (_event, request) =>
-      runHostSync(request as SyncUiRunRequest),
-    );
-    deps.ipcMain.handle(channels.syncUiCancelRun, () => cancelRun());
-    deps.ipcMain.handle(channels.syncUiCheckHost, (_event, host) => checkHost(String(host)));
-    deps.ipcMain.handle(channels.syncUiCreateSnapshot, () => createSnapshot());
-    deps.ipcMain.handle(channels.syncUiMergeSnapshotFile, (_event, filePath, force) =>
-      mergeSnapshotFile(String(filePath), force === true),
-    );
-    deps.ipcMain.handle(channels.syncUiDeleteSnapshot, (_event, filePath) =>
-      deleteSnapshot(String(filePath)),
-    );
-    deps.ipcMain.handle(channels.syncUiRevealSnapshot, (_event, filePath) => {
-      deps.revealPath(String(filePath));
-      return true;
-    });
-    deps.ipcMain.handle(channels.syncUiPickSnapshotFile, () => deps.pickSnapshotFile());
  }

  return {
    registerHandlers,
    getSnapshot,
-    readState,
+    readState: hostsState.readState,
    runHostSync,
-    checkHost,
-    cancelRun,
-    shutdown,
-    isRunning: () => currentRun !== null,
+    checkHost: runLifecycle.checkHost,
+    cancelRun: runLifecycle.cancelRun,
+    shutdown: runLifecycle.shutdown,
+    isRunning: runLifecycle.isRunning,
  };
 }
@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { SyncUiSnapshotFile, SyncUiStartResult } from '../../types/sync-ui';
+
+interface SyncUiSnapshotsDeps {
+  snapshotsDir: string;
+  nowMs: () => number;
+  startRun: (kind: 'snapshot' | 'merge', host: null, args: string[]) => SyncUiStartResult;
+  broadcastStateChanged: () => void;
+}
+
+function formatSnapshotName(nowMs: number): string {
+  // Milliseconds prevent snapshots taken in the same second from overwriting each other.
+  const iso = new Date(nowMs).toISOString();
+  const stamp = iso.slice(0, 23).replace(/[-:.]/g, '').replace('T', '-');
+  return `immersion-${stamp}.sqlite`;
+}
+
+export function createSyncUiSnapshots(deps: SyncUiSnapshotsDeps) {
+  function listSnapshots(): SyncUiSnapshotFile[] {
+    let names: string[];
+    try {
+      names = fs.readdirSync(deps.snapshotsDir);
+    } catch {
+      return [];
+    }
+    const files: SyncUiSnapshotFile[] = [];
+    for (const name of names) {
+      if (!name.endsWith('.sqlite')) continue;
+      const filePath = path.join(deps.snapshotsDir, name);
+      try {
+        const stat = fs.statSync(filePath);
+        if (!stat.isFile()) continue;
+        files.push({
+          path: filePath,
+          name,
+          sizeBytes: stat.size,
+          modifiedAtMs: stat.mtimeMs,
+        });
+      } catch {
+        // file disappeared between readdir and stat
+      }
+    }
+    files.sort((a, b) => b.modifiedAtMs - a.modifiedAtMs);
+    return files;
+  }
+
+  function createSnapshot(): SyncUiStartResult {
+    const outPath = path.join(deps.snapshotsDir, formatSnapshotName(deps.nowMs()));
+    return deps.startRun('snapshot', null, ['sync', '--snapshot', outPath, '--json']);
+  }
+
+  function mergeSnapshotFile(filePath: string, force = false): SyncUiStartResult {
+    if (!fs.existsSync(filePath)) {
+      return { started: false, runId: null, reason: `Snapshot file not found: ${filePath}` };
+    }
+    const args = ['sync', '--merge', filePath];
+    if (force) args.push('--force');
+    args.push('--json');
+    return deps.startRun('merge', null, args);
+  }
+
+  function deleteSnapshot(filePath: string): void {
+    const resolved = path.resolve(filePath);
+    const dir = path.resolve(deps.snapshotsDir);
+    if (resolved !== path.join(dir, path.basename(resolved)) || !resolved.endsWith('.sqlite')) {
+      throw new Error('Refusing to delete a file outside the snapshots directory.');
+    }
+    fs.rmSync(resolved, { force: true });
+    deps.broadcastStateChanged();
+  }
+
+  return { listSnapshots, createSnapshot, mergeSnapshotFile, deleteSnapshot };
+}
@@ -1,7 +1,7 @@
 import fs from 'node:fs';
-import net from 'node:net';
 import { spawn, spawnSync } from 'node:child_process';
 import { isLogFileEnabled } from '../../shared/log-files';
+import { canConnectSocket } from '../../shared/socket-probe';
 import { buildMpvLaunchModeArgs } from '../../shared/mpv-launch-mode';
 import { buildMpvMsgLevel } from '../../shared/mpv-logging-args';
 import { buildSubminerPluginRuntimeScriptOptParts } from '../../shared/subminer-plugin-script-opts';
@@ -93,28 +93,6 @@ async function sleepMs(ms: number): Promise<void> {
  await new Promise<void>((resolve) => setTimeout(resolve, ms));
 }

-async function canConnectSocket(socketPath: string): Promise<boolean> {
-  return await new Promise<boolean>((resolve) => {
-    const socket = net.createConnection(socketPath);
-    let settled = false;
-
-    const finish = (value: boolean): void => {
-      if (settled) return;
-      settled = true;
-      try {
-        socket.destroy();
-      } catch {
-        // ignore
-      }
-      resolve(value);
-    };
-
-    socket.once('connect', () => finish(true));
-    socket.once('error', () => finish(false));
-    socket.setTimeout(400, () => finish(false));
-  });
-}
-
 async function waitForSocketReady(socketPath: string, timeoutMs: number): Promise<boolean> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
@@ -0,0 +1,34 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { handleSyncCliAtEntry } from './sync-cli';
+
+test('handleSyncCliAtEntry exits through the process exit dependency', async () => {
+  const exits: number[] = [];
+  const handled = await handleSyncCliAtEntry(
+    ['SubMiner', '--sync-cli', 'sync', '--make-temp'],
+    {},
+    '0.18.0',
+    {
+      run: async () => 7,
+      exit: (code) => {
+        exits.push(code);
+      },
+    },
+  );
+
+  assert.equal(handled, true);
+  assert.deepEqual(exits, [7]);
+});
+
+test('handleSyncCliAtEntry ignores normal GUI startup', async () => {
+  const handled = await handleSyncCliAtEntry(['SubMiner', '--start'], {}, '0.18.0', {
+    run: async () => {
+      throw new Error('should not run');
+    },
+    exit: () => {
+      throw new Error('should not exit');
+    },
+  });
+
+  assert.equal(handled, false);
+});
@@ -1,20 +1,15 @@
 import fs from 'node:fs';
-import net from 'node:net';
-import os from 'node:os';
-import path from 'node:path';
-import { parse as parseJsonc } from 'jsonc-parser';
-import { resolveConfigDir, resolveConfigFilePath } from '../config/path-resolution';
 import { getDefaultMpvSocketPath } from '../shared/mpv-socket-path';
+import { canConnectSocket } from '../shared/socket-probe';
+import { getDefaultConfigDir } from '../shared/setup-state';
 import {
  extractSyncCliTokens,
  parseSyncCliTokens,
  syncCliUsage,
 } from '../core/services/stats-sync/cli-args';
-import {
-  createDbSnapshot,
-  findLiveStatsDaemonPid,
-} from '../core/services/stats-sync/shared';
-import { formatMergeSummary, mergeSnapshotIntoDb } from '../core/services/stats-sync/merge';
+import { resolveImmersionDbPath } from '../core/services/stats-sync/db-path';
+import { createDbSnapshot, findLiveStatsDaemonPid } from '../core/services/stats-sync/shared';
+import { mergeSnapshotIntoDb } from '../core/services/stats-sync/merge';
 import {
  assertSafeSshHost,
  detectRemoteShellFlavor,
@@ -22,88 +17,33 @@ import {
  runScp,
  runSsh,
 } from '../core/services/stats-sync/ssh';
-import { openLibsqlSyncDb } from '../core/services/stats-sync/libsql-driver';
 import {
  ensureTrackerQuiescentFlow,
  runSyncFlow,
  type SyncFlowDeps,
 } from '../core/services/stats-sync/sync-flow';
-import { recordSyncResult, readSyncHostsState, writeSyncHostsState, getSyncHostsPath } from '../shared/sync/sync-hosts-store';
+import {
+  recordSyncResult,
+  readSyncHostsState,
+  writeSyncHostsState,
+  getSyncHostsPath,
+} from '../shared/sync/sync-hosts-store';

-export function shouldHandleSyncCliAtEntry(argv: readonly string[], env: NodeJS.ProcessEnv): boolean {
+export function shouldHandleSyncCliAtEntry(
+  argv: readonly string[],
+  env: NodeJS.ProcessEnv,
+): boolean {
  if (env.ELECTRON_RUN_AS_NODE === '1') return false;
  return extractSyncCliTokens(argv) !== null;
 }

-function resolveAppConfigDir(): string {
-  return resolveConfigDir({
-    platform: process.platform,
-    appDataDir: process.env.APPDATA,
-    xdgConfigHome: process.env.XDG_CONFIG_HOME,
-    homeDir: os.homedir(),
-    existsSync: fs.existsSync,
-  });
-}
-
-function resolveTildePath(input: string): string {
-  return input.startsWith('~') ? path.join(os.homedir(), input.slice(1)) : path.resolve(input);
-}
-
-// Same resolution as the launcher: honor a configured immersionTracking.dbPath
-// (raw config read, tolerant of comments), else <configDir>/immersion.sqlite.
-function resolveDefaultDbPath(): string {
-  const configPath = resolveConfigFilePath({
-    appDataDir: process.env.APPDATA,
-    xdgConfigHome: process.env.XDG_CONFIG_HOME,
-    homeDir: os.homedir(),
-    existsSync: fs.existsSync,
-  });
-  let configured = '';
-  try {
-    const data = fs.readFileSync(configPath, 'utf8');
-    const parsed = configPath.endsWith('.jsonc') ? parseJsonc(data) : JSON.parse(data);
-    const tracking =
-      parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-        ? (parsed as Record<string, unknown>).immersionTracking
-        : null;
-    if (tracking && typeof tracking === 'object' && !Array.isArray(tracking)) {
-      const dbPath = (tracking as Record<string, unknown>).dbPath;
-      if (typeof dbPath === 'string') configured = dbPath.trim();
-    }
-  } catch {
-    // no config or unreadable config → default location
-  }
-  if (configured) return resolveTildePath(configured);
-  return path.join(resolveAppConfigDir(), 'immersion.sqlite');
-}
-
-async function canConnectUnixSocket(socketPath: string): Promise<boolean> {
-  return await new Promise<boolean>((resolve) => {
-    const socket = net.createConnection(socketPath);
-    let settled = false;
-    const finish = (value: boolean) => {
-      if (settled) return;
-      settled = true;
-      try {
-        socket.destroy();
-      } catch {
-        // ignore
-      }
-      resolve(value);
-    };
-    socket.once('connect', () => finish(true));
-    socket.once('error', () => finish(false));
-    socket.setTimeout(400, () => finish(false));
-  });
-}
-
 function recordHostSyncResultToDisk(
  host: string,
  status: 'success' | 'error',
  detail: string | null,
 ): void {
  try {
-    const filePath = getSyncHostsPath(resolveAppConfigDir());
+    const filePath = getSyncHostsPath(getDefaultConfigDir());
    const state = recordSyncResult(readSyncHostsState(filePath), host, {
      atMs: Date.now(),
      status,
@@ -117,24 +57,15 @@ function recordHostSyncResultToDisk(

 function buildSyncCliDeps(): SyncFlowDeps {
  const deps: SyncFlowDeps = {
-    createDbSnapshot: (dbPath, outPath) => createDbSnapshot(openLibsqlSyncDb, dbPath, outPath),
-    mergeSnapshotIntoDb: (localDbPath, snapshotPath) =>
-      mergeSnapshotIntoDb(openLibsqlSyncDb, localDbPath, snapshotPath),
-    formatMergeSummary,
+    createDbSnapshot,
+    mergeSnapshotIntoDb,
    findLiveStatsDaemonPid,
    assertSafeSshHost,
    detectRemoteShellFlavor,
    resolveRemoteSubminerCommand,
    runScp,
    runSsh,
-    fail: (message: string): never => {
-      throw new Error(message);
-    },
-    log: (level, configured, message) => {
-      if (level === 'debug' && configured !== 'debug') return;
-      console.error(message);
-    },
-    canConnectUnixSocket,
+    canConnectUnixSocket: canConnectSocket,
    realpathSync: (candidate) => fs.realpathSync(candidate),
    mkdtempSync: (prefix) => fs.mkdtempSync(prefix),
    rmSync: (target, options) => fs.rmSync(target, options),
@@ -144,8 +75,7 @@ function buildSyncCliDeps(): SyncFlowDeps {
      ensureTrackerQuiescentFlow(context, dbPath, deps),
    emitEvent: () => {},
    recordHostSyncResult: recordHostSyncResultToDisk,
-    resolveDefaultDbPath,
-    resolvePath: resolveTildePath,
+    resolveDefaultDbPath: resolveImmersionDbPath,
  };
  return deps;
 }
@@ -188,3 +118,23 @@ export async function runSyncCliFromProcess(
    return 1;
  }
 }
+
+export async function handleSyncCliAtEntry(
+  argv: readonly string[],
+  env: NodeJS.ProcessEnv,
+  appVersion: string,
+  deps: {
+    run: typeof runSyncCliFromProcess;
+    exit: (code: number) => void;
+  } = {
+    run: runSyncCliFromProcess,
+    exit: (code) => process.exit(code),
+  },
+): Promise<boolean> {
+  if (!shouldHandleSyncCliAtEntry(argv, env)) return false;
+  const exitCode = await deps.run(argv, appVersion);
+  // This path runs before app readiness and must not call app.exit(): on Linux
+  // that can throw and make the entrypoint fall back to full GUI startup.
+  deps.exit(exitCode);
+  return true;
+}
@@ -1,25 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { IPC_CHANNELS } from './shared/ipc/contracts';
 import type {
-  SyncHostsState,
  SyncUiAPI,
  SyncUiCheckResult,
  SyncUiHostUpdateRequest,
  SyncUiProgressPayload,
  SyncUiRunRequest,
  SyncUiSnapshot,
-  SyncUiSnapshotFile,
  SyncUiStartResult,
 } from './types/sync-ui';

 const syncUiAPI: SyncUiAPI = {
  getSnapshot: (): Promise<SyncUiSnapshot> =>
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiGetSnapshot),
-  saveHost: (update: SyncUiHostUpdateRequest): Promise<SyncHostsState> =>
+  saveHost: (update: SyncUiHostUpdateRequest): Promise<void> =>
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiSaveHost, update),
-  removeHost: (host: string): Promise<SyncHostsState> =>
+  removeHost: (host: string): Promise<void> =>
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiRemoveHost, host),
-  setAutoSyncInterval: (minutes: number): Promise<SyncHostsState> =>
+  setAutoSyncInterval: (minutes: number): Promise<void> =>
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiSetAutoSyncInterval, minutes),
  runSync: (request: SyncUiRunRequest): Promise<SyncUiStartResult> =>
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiRunSync, request),
@@ -30,7 +28,7 @@ const syncUiAPI: SyncUiAPI = {
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiCreateSnapshot),
  mergeSnapshotFile: (path: string, force?: boolean): Promise<SyncUiStartResult> =>
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiMergeSnapshotFile, path, force === true),
-  deleteSnapshot: (path: string): Promise<SyncUiSnapshotFile[]> =>
+  deleteSnapshot: (path: string): Promise<void> =>
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiDeleteSnapshot, path),
  revealSnapshot: (path: string): Promise<boolean> =>
    ipcRenderer.invoke(IPC_CHANNELS.request.syncUiRevealSnapshot, path),
@@ -0,0 +1,28 @@
+import net from 'node:net';
+
+/**
+ * True when something is accepting connections on the unix socket / Windows
+ * named pipe (400 ms probe). Electron-free; shared by the sync CLI's
+ * running-app guard and the Windows mpv launch attach wait.
+ */
+export async function canConnectSocket(socketPath: string): Promise<boolean> {
+  return await new Promise<boolean>((resolve) => {
+    const socket = net.createConnection(socketPath);
+    let settled = false;
+
+    const finish = (value: boolean): void => {
+      if (settled) return;
+      settled = true;
+      try {
+        socket.destroy();
+      } catch {
+        // ignore
+      }
+      resolve(value);
+    };
+
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+    socket.setTimeout(400, () => finish(false));
+  });
+}
@@ -1,6 +1,6 @@
 // NDJSON progress protocol emitted by `subminer sync --json` and consumed by
-// the sync UI's launcher client. Keep this file free of Electron/bun imports —
-// it is shared between the launcher (bun) and the app main process (node).
+// the sync UI's launcher client. Avoid Electron/bun imports because this file
+// is shared between the launcher (bun) and the app main process (node).

 export interface SyncMergeSummary {
  sessionsMerged: number;
@@ -65,10 +65,7 @@ body {
  height: 100%;
  margin: 0;
  overflow: hidden;
-  background:
-    radial-gradient(1200px 480px at 85% -10%, rgba(138, 173, 244, 0.09), transparent 60%),
-    radial-gradient(900px 420px at -10% 110%, rgba(198, 160, 246, 0.07), transparent 55%),
-    var(--ctp-base);
+  background: var(--ctp-base);
  color: var(--text);
  font-family:
    'M PLUS 1', 'Avenir Next', 'Hiragino Sans', 'Hiragino Kaku Gothic ProN', 'Yu Gothic', sans-serif;
@@ -278,18 +275,6 @@ input {
  color: var(--muted);
 }

-.banner {
-  border-radius: 10px;
-  padding: 10px 14px;
-  font-size: 13px;
-}
-
-.banner-warn {
-  border: 1px solid rgba(245, 169, 127, 0.4);
-  background: rgba(245, 169, 127, 0.08);
-  color: var(--warn);
-}
-
 .empty-note {
  padding: 14px 4px 4px;
  font-size: 13px;
@@ -167,8 +167,8 @@ function handleProgress(payload: SyncUiProgressPayload): void {
  } else if (event.type === 'merge-summary') {
    appendMergeSummary(event.target, summarizeMergeCounts(event.summary));
  } else if (event.type === 'result') {
+    // The run's completion handler broadcasts state-changed, which refreshes.
    showResult(event.ok, event.error);
-    void refresh();
  }
 }

@@ -240,7 +240,8 @@ function renderHostCard(entry: SyncHostEntry): HTMLDivElement {
    button.title = direction.title;
    button.classList.toggle('active', entry.direction === direction.id);
    button.addEventListener('click', () => {
-      void api.saveHost({ host: entry.host, direction: direction.id }).then(refreshFromState);
+      // Every mutation triggers a state-changed broadcast, which refreshes.
+      void api.saveHost({ host: entry.host, direction: direction.id });
    });
    toggle.appendChild(button);
  }
@@ -251,7 +252,7 @@ function renderHostCard(entry: SyncHostEntry): HTMLDivElement {
  autoBox.type = 'checkbox';
  autoBox.checked = entry.autoSync;
  autoBox.addEventListener('change', () => {
-    void api.saveHost({ host: entry.host, autoSync: autoBox.checked }).then(refreshFromState);
+    void api.saveHost({ host: entry.host, autoSync: autoBox.checked });
  });
  const autoText = document.createElement('span');
  autoText.textContent = 'Auto-sync';
@@ -288,7 +289,7 @@ function renderHostCard(entry: SyncHostEntry): HTMLDivElement {
  removeButton.textContent = 'Remove';
  removeButton.addEventListener('click', () => {
    if (!window.confirm(`Remove ${entry.host} from saved devices?`)) return;
-    void api.removeHost(entry.host).then(refreshFromState);
+    void api.removeHost(entry.host);
  });
  actions.append(syncButton, testButton, removeButton);

@@ -367,7 +368,7 @@ function renderSnapshots(): void {
      remove.textContent = 'Delete';
      remove.addEventListener('click', () => {
        if (!window.confirm(`Delete snapshot ${file.name}?`)) return;
-        void api.deleteSnapshot(file.path).then(refreshFromState);
+        void api.deleteSnapshot(file.path);
      });
      actions.append(merge, reveal, remove);
      row.append(name, meta, actions);
@@ -408,7 +409,6 @@ addHostButton.addEventListener('click', () => {
      newHostInput.value = '';
      newLabelInput.value = '';
      checkResultEl.classList.add('hidden');
-      return refresh();
    })
    .catch((error: unknown) => {
      renderCheckResult({
@@ -446,7 +446,7 @@ testHostButton.addEventListener('click', () => {
 autoIntervalInput.addEventListener('change', () => {
  const minutes = Number(autoIntervalInput.value);
  if (!Number.isFinite(minutes) || minutes < 1) return;
-  void api.setAutoSyncInterval(Math.floor(minutes)).then(refreshFromState);
+  void api.setAutoSyncInterval(Math.floor(minutes));
 });

 cancelButton.addEventListener('click', () => {
@@ -65,15 +65,15 @@ export interface SyncUiHostUpdateRequest {

 export interface SyncUiAPI {
  getSnapshot: () => Promise<SyncUiSnapshot>;
-  saveHost: (update: SyncUiHostUpdateRequest) => Promise<SyncHostsState>;
-  removeHost: (host: string) => Promise<SyncHostsState>;
-  setAutoSyncInterval: (minutes: number) => Promise<SyncHostsState>;
+  saveHost: (update: SyncUiHostUpdateRequest) => Promise<void>;
+  removeHost: (host: string) => Promise<void>;
+  setAutoSyncInterval: (minutes: number) => Promise<void>;
  runSync: (request: SyncUiRunRequest) => Promise<SyncUiStartResult>;
  cancelRun: () => Promise<boolean>;
  checkHost: (host: string) => Promise<SyncUiCheckResult>;
  createSnapshot: () => Promise<SyncUiStartResult>;
  mergeSnapshotFile: (path: string, force?: boolean) => Promise<SyncUiStartResult>;
-  deleteSnapshot: (path: string) => Promise<SyncUiSnapshotFile[]>;
+  deleteSnapshot: (path: string) => Promise<void>;
  revealSnapshot: (path: string) => Promise<boolean>;
  pickSnapshotFile: () => Promise<string | null>;
  onProgress: (listener: (payload: SyncUiProgressPayload) => void) => () => void;
Author	SHA1	Message	Date
sudacode	37dcec25eb	feat(sync): drop quiescence guard in favor of live WAL-based sync - Remove `canAutoSync` dep from scheduler; auto-sync now runs during playback/stats - Sync window always passes `--force`; WAL snapshots and transactional merges handle concurrent writers - Update docs to clarify live vs cold-start sync modes	2026-07-13 03:29:07 -07:00
sudacode	4a10257bc9	feat(sync): emit structured remote merge-summary event - Remote merge step now passes --json to get NDJSON output - Parses merge-summary from remote stdout; emits as merge-summary/remote event - Falls back to remote-output for non-JSON runs - Updates docs and changelog to reflect per-machine merge summaries	2026-07-13 02:40:59 -07:00
sudacode	4c63f7e3b0	fix(sync): decode multibyte output correctly and settle on exit drain - Use StringDecoder to avoid corrupting multibyte chars (e.g. Japanese titles) split across stdout/stderr chunks - Settle a run within EXIT_DRAIN_MS (2s) after child exit when no terminal NDJSON arrives, instead of waiting on `close` that retained pipes can withhold indefinitely	2026-07-13 00:09:11 -07:00
sudacode	8c97b48721	fix(sync-ui): quit reliably after standalone sync window closes - Re-issue post-cleanup quit via setImmediate so Electron doesn't drop it while unwinding the prevented quit - Use requestAppQuit (not app.quit) on sync window close for forced-exit fallback coverage - Settle cancelled/timed-out runs immediately when child already exited to avoid hanging on close held open by descendants	2026-07-12 23:59:20 -07:00
sudacode	8ae77b296d	fix(sync-ui): remove background gradient overlays - Simplify body background to flat --ctp-base color, dropping the radial gradients	2026-07-12 23:22:44 -07:00
sudacode	32d0c79edd	fix(sync-ui): preserve headless child arguments	2026-07-12 23:21:51 -07:00
sudacode	89e5ac60f6	refactor(sync-ui): split runtime into focused modules - Extract sync-ui-runtime.ts into sync-ui-hosts-state, sync-ui-ipc-handlers, sync-ui-run-lifecycle, sync-ui-snapshots - Reject sync --ui combined with --remote-cmd or --db in cli-parser-builder	2026-07-12 23:04:59 -07:00
sudacode	247549fcfe	docs: update sync documentation	2026-07-12 23:04:08 -07:00
sudacode	806c56a99b	refactor(sync): collapse 11 sync args into forwarded token array - Replace syncHost/syncSnapshotPath/… with syncCliTokens: string[] passed verbatim to --sync-cli sync - Move sync CLI validation from launcher to parseSyncCliTokens (app-side single owner) - Extract resolveImmersionDbPath to shared db-path.ts importable by both launcher and app - Delete driver.ts; inline types into libsql-driver.ts and hard-wire openLibsqlSyncDb - Drop OpenSyncDb injection from mergeSnapshotIntoDb and createDbSnapshot	2026-07-12 22:31:59 -07:00
sudacode	344a8b44c0	fix(sync): settle launcher client only after terminal NDJSON on exit - `runSyncLauncher`: defer exit settlement until result event parsed; handle exit-before-stdout race - AppImage sync commands now run in Node-only mode (`ELECTRON_RUN_AS_NODE=1 -e ...`) so remote sync needs no display server - Update docs and changelog to reflect both changes	2026-07-12 20:11:14 -07:00
sudacode	5d8673f299	fix(sync): harden detached launch, bounded --check probes, and pipe-clos - `sync --ui` now launches detached; closing standalone Sync window exits app - `--check` uses BatchMode + ConnectTimeout + 15s timeoutMs on all SSH calls - `runSyncLauncher` settles on `exit` (not just `close`) for Electron pipe inheritance - Added `timeoutMs` to `runSyncLauncher`; check-host passes 30s deadline - `handleSyncCliAtEntry` wraps exit deps for testability; fixes Linux AppImage GUI fallthrough - `config-settings-window` gains optional `onClosed` hook - Added preload-syncui bundle to `build:syncui` script	2026-07-12 19:42:34 -07:00